strobe 0.0.1__tar.gz

strobe-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint and Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Sync dependencies
+        run: uv sync --group test --group dev
+
+      - name: Run ruff check
+        run: uv run ruff check strobe tests
+
+      - name: Run ruff format check
+        run: uv run ruff format --check strobe tests
+
+      - name: Run mypy type check
+        run: uv run mypy strobe --ignore-missing-imports --no-error-summary
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Sync dependencies
+        run: uv sync --group test
+
+      - name: Run tests
+        run: uv run pytest
+
+  pre-commit:
+    name: Pre-commit hooks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.0

strobe-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: publish
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v2
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

strobe-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+*.egg-info
+__pycache__/
+/.venv/
+/.idea/
+strobe/_version.py

strobe-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+      - id: check-merge-conflict
+      - id: debug-statements
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.1
+    hooks:
+      - id: mypy
+        args: [--ignore-missing-imports, --no-error-summary]

strobe-0.0.1/CLAUDE.md

@@ -0,0 +1,140 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`strobe` is a Python package (requires Python >=3.13) managed with `uv`. It provides instrumentation methods
+for recording execution events on different kinds of agent frameworks. Then it provides a set of tools to analyze
+the recorded events and study the behavior of the agents. For that it makes use of process mining techniques such as
+process discovery, process performance analysis, compliance and conformance analysis, and other process mining techniques.
+
+## Commands
+
+```bash
+# Install dependencies (including test group)
+uv sync --group test
+
+# Install dev dependencies (includes linting, formatting, pre-commit)
+uv sync --group dev
+
+# Run all tests
+uv run pytest
+
+# Run a single test file
+uv run pytest tests/path/to/test_file.py
+
+# Run a single test by name
+uv run pytest tests/path/to/test_file.py::test_name
+
+# Run tests matching a keyword
+uv run pytest -k "keyword"
+```
+
+## Pre-commit Hooks
+
+Pre-commit hooks are configured to run automatically before each commit. Install them with:
+
+```bash
+pre-commit install
+```
+
+Hooks run:
+- **ruff check**: Linting with Ruff (auto-fixes when possible)
+- **ruff format**: Code formatting with Ruff
+- **mypy**: Static type checking
+- **Basic checks**: Trailing whitespace, end-of-file fixers, YAML/JSON validation, merge conflict detection
+
+To run hooks manually on all files:
+
+```bash
+pre-commit run --all-files
+```
+
+## CI/CD
+
+GitHub Actions workflows run the same checks on pull requests and pushes to `main`:
+- `.github/workflows/ci.yml`: Runs linting, formatting, type checking, and tests
+
+## Architecture
+
+The library has three main layers:
+
+- **Instrumentation** (`strobe.instrumentation`): decorators/hooks/callbacks that integrate with agent frameworks to capture execution events (e.g. tool calls, LLM invocations, agent steps) and record them as event logs.
+- **Analysis** (`strobe.analysis`): process mining tools that operate on the recorded event logs — process discovery, performance analysis, conformance checking, and other process mining techniques.
+- **Visualization** (`strobe.visualization`): interactive Plotly charts and a Streamlit dashboard for exploring analysis results.
+
+### Module layout
+
+```
+strobe/
+  __init__.py                        # re-exports StrobePlugin + key analysis/viz functions
+  instrumentation/
+    __init__.py                      # exports StrobePlugin, EventLog
+    event_log.py                     # EventLog: internal buffer → DataFrame / XES
+    plugin.py                        # StrobePlugin: ADK BasePlugin implementation
+  analysis/
+    __init__.py                      # exports discover_dfg, discover_process_model,
+                                     #   check_conformance, throughput_times, activity_statistics
+    discovery.py                     # DFG and Petri net discovery wrappers
+    conformance.py                   # token-based replay conformance checking
+    performance.py                   # throughput times, per-activity stats
+  visualization/
+    __init__.py                      # exports plot_* functions + launch_dashboard
+    plots.py                         # pure Plotly figure factories (no Streamlit import)
+    app.py                           # Streamlit dashboard + launch_dashboard()
+
+tests/
+  instrumentation/
+    test_event_log.py
+    test_plugin.py
+  analysis/
+    test_discovery.py
+    test_conformance.py
+    test_performance.py
+  visualization/
+    test_plots.py
+```
+
+### Key types
+
+| Symbol | Module | Description |
+|---|---|---|
+| `EventLog` | `strobe.instrumentation.event_log` | Accumulates events; exports XES / DataFrame |
+| `StrobePlugin` | `strobe.instrumentation.plugin` | ADK `BasePlugin`; records tool/LLM/agent callbacks |
+| `discover_dfg` | `strobe.analysis.discovery` | Returns `(dfg, start_acts, end_acts)` |
+| `discover_process_model` | `strobe.analysis.discovery` | Returns `(net, im, fm)`; supports inductive & alpha |
+| `check_conformance` | `strobe.analysis.conformance` | Returns fitness/precision/generalization/simplicity |
+| `throughput_times` | `strobe.analysis.performance` | Per-case duration `Series` |
+| `activity_statistics` | `strobe.analysis.performance` | Per-activity count + duration stats `DataFrame` |
+| `plot_dfg` | `strobe.visualization.plots` | Plotly DFG figure (nodes + weighted edges) |
+| `plot_petri_net` | `strobe.visualization.plots` | Plotly Petri net figure (places/transitions) |
+| `plot_throughput_times` | `strobe.visualization.plots` | Violin plot of case durations |
+| `plot_activity_statistics` | `strobe.visualization.plots` | Dual-axis bar chart (count + mean duration) |
+| `plot_conformance` | `strobe.visualization.plots` | Horizontal bar chart of 4 conformance metrics |
+| `launch_dashboard` | `strobe.visualization.app` | Starts Streamlit dashboard via subprocess |
+
+### Running the dashboard
+
+```bash
+# Direct
+streamlit run strobe/visualization/app.py
+
+# From Python (programmatic, e.g. after saving a XES file)
+from strobe import launch_dashboard
+proc = launch_dashboard(xes_path="path/to/log.xes")
+```
+
+### XES event attribute mapping
+
+| ADK concept | XES attribute | Example |
+|---|---|---|
+| `invocation_id` | `case:concept:name` | `"inv-abc123"` |
+| activity | `concept:name` | `"tool:search"`, `"llm:gemini-2.0"`, `"agent:root_agent"` |
+| completion time | `time:timestamp` | `datetime(...)` |
+| start time | `strobe:start_time` | ISO string |
+| wall-clock duration | `strobe:duration_s` | `1.23` |
+| tool args | `strobe:tool_args` | JSON string |
+| tool result | `strobe:tool_result` | JSON string |
+| model name | `strobe:model_name` | `"gemini-2.0-flash"` |
+| tokens in/out | `strobe:input_tokens`, `strobe:output_tokens` | `123`, `456` |

strobe-0.0.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: strobe
+Version: 0.0.1
+Summary: Process Mining & Agent Instrumentation for AI Agent Frameworks
+Requires-Python: >=3.13
+Requires-Dist: google-adk>=1.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: pm4py>=2.7.0
+Requires-Dist: streamlit>=1.32.0

strobe-0.0.1/README.md

@@ -0,0 +1,261 @@
+# strobe
+
+**Process Mining & Agent Instrumentation for AI Agent Frameworks**
+
+`strobe` is a Python package that instruments AI agent frameworks to capture execution events and analyze agent behavior using process mining techniques. It helps you understand, visualize, and optimize how your agents execute.
+
+## Features
+
+- 🎯 **Event Instrumentation**: Decorators and plugins to capture agent execution events (tool calls, LLM invocations, agent steps)
+- 🔬 **Process Discovery**: Automatically discover process models from execution traces (Directly-Follows Graphs, Petri nets)
+- 📊 **Performance Analysis**: Throughput times, activity statistics, and bottleneck detection
+- ✅ **Conformance Checking**: Verify if agent behavior conforms to expected process specifications
+- 📈 **Interactive Visualization**: Beautiful Plotly charts and Streamlit dashboard for exploring results
+- 📁 **Standard Formats**: Export/import event logs in XES (eXtensible Event Stream) format
+
+## Installation
+
+### Requirements
+- Python >= 3.13
+- `uv` package manager (see [https://docs.astral.sh/uv/](https://docs.astral.sh/uv/))
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd strobe
+
+# Install dependencies (including test dependencies)
+uv sync --group test
+```
+
+## Quick Start
+
+### 1. Instrument Your Agent
+
+Use `StrobePlugin` to capture events from your agent framework:
+
+```python
+from strobe import StrobePlugin, EventLog
+
+# Create a plugin and event log
+plugin = StrobePlugin(event_log=EventLog())
+
+# Register with your agent framework (e.g., Google ADK)
+# The plugin automatically captures:
+# - Tool invocations
+# - LLM calls
+# - Agent steps
+```
+
+### 2. Discover Process Models
+
+Analyze the captured events to discover how your agent actually behaves:
+
+```python
+from strobe import discover_dfg, discover_process_model
+
+# Extract a Directly-Follows Graph (DFG)
+dfg, start_acts, end_acts = discover_dfg(event_log)
+
+# Or discover a Petri net process model
+net, initial_marking, final_marking = discover_process_model(event_log, method='inductive')
+```
+
+### 3. Visualize Results
+
+Create interactive visualizations of discovered processes:
+
+```python
+from strobe import plot_dfg, plot_petri_net
+
+# Plot the DFG with hierarchical flowchart layout
+fig = plot_dfg(dfg, start_acts, end_acts)
+fig.show()
+
+# Plot the Petri net
+fig = plot_petri_net(net, initial_marking, final_marking)
+fig.show()
+```
+
+### 4. Analyze Performance
+
+Get detailed performance metrics:
+
+```python
+from strobe import throughput_times, activity_statistics, plot_activity_statistics
+
+# Per-case throughput times
+times = throughput_times(event_log)
+print(f"Mean execution time: {times.mean()}")
+
+# Per-activity statistics
+stats = activity_statistics(event_log)
+fig = plot_activity_statistics(stats)
+fig.show()
+```
+
+### 5. Check Conformance
+
+Verify if execution traces conform to a process model:
+
+```python
+from strobe import check_conformance
+
+# Token-based replay conformance checking
+scores = check_conformance(event_log, net, initial_marking, final_marking)
+print(f"Fitness: {scores['fitness']:.3f}")
+print(f"Precision: {scores['precision']:.3f}")
+print(f"Generalization: {scores['generalization']:.3f}")
+print(f"Simplicity: {scores['simplicity']:.3f}")
+```
+
+### 6. Launch Interactive Dashboard
+
+View and explore your analysis results in an interactive Streamlit dashboard:
+
+```python
+from strobe import launch_dashboard
+
+# Launch dashboard and serve a saved XES log
+proc = launch_dashboard(xes_path="path/to/execution_log.xes")
+```
+
+Or run it directly:
+```bash
+streamlit run strobe/visualization/app.py
+```
+
+## Architecture
+
+strobe has three main layers:
+
+### 1. Instrumentation (`strobe.instrumentation`)
+Captures execution events from agent frameworks via callbacks/plugins:
+- `StrobePlugin`: Integrates with agent framework (ADK BasePlugin)
+- `EventLog`: Accumulates events and exports to DataFrame/XES
+
+### 2. Analysis (`strobe.analysis`)
+Process mining algorithms operating on event logs:
+- **Discovery**: Extract Directly-Follows Graphs (DFG) and Petri nets
+- **Performance**: Throughput times and activity statistics
+- **Conformance**: Token-based replay conformance checking
+
+### 3. Visualization (`strobe.visualization`)
+Interactive charts and dashboards:
+- **Plots**: Plotly figure factories (hierarchical flowcharts, Petri nets, statistics)
+- **Dashboard**: Streamlit app for exploring results
+
+### Module Structure
+
+```
+strobe/
+├── __init__.py                  # Main API exports
+├── instrumentation/
+│   ├── event_log.py             # EventLog class
+│   └── plugin.py                # StrobePlugin (ADK integration)
+├── analysis/
+│   ├── discovery.py             # Process discovery
+│   ├── conformance.py           # Conformance checking
+│   └── performance.py           # Performance analysis
+└── visualization/
+    ├── plots.py                 # Plotly figure factories
+    └── app.py                   # Streamlit dashboard
+```
+
+## API Reference
+
+### Key Classes
+
+| Name | Module | Purpose |
+|------|--------|---------|
+| `EventLog` | `strobe.instrumentation` | Buffer and export execution events |
+| `StrobePlugin` | `strobe.instrumentation` | ADK plugin for event capture |
+
+### Key Functions
+
+| Name | Module | Returns |
+|------|--------|---------|
+| `discover_dfg` | `strobe.analysis` | `(dfg, start_acts, end_acts)` |
+| `discover_process_model` | `strobe.analysis` | `(net, im, fm)` |
+| `check_conformance` | `strobe.analysis` | `dict[str, float]` (fitness, precision, generalization, simplicity) |
+| `throughput_times` | `strobe.analysis` | `pd.Series` |
+| `activity_statistics` | `strobe.analysis` | `pd.DataFrame` |
+| `plot_dfg` | `strobe.visualization` | `plotly.graph_objects.Figure` |
+| `plot_petri_net` | `strobe.visualization` | `plotly.graph_objects.Figure` |
+| `plot_activity_statistics` | `strobe.visualization` | `plotly.graph_objects.Figure` |
+| `plot_conformance` | `strobe.visualization` | `plotly.graph_objects.Figure` |
+| `launch_dashboard` | `strobe.visualization` | Process handle |
+
+## Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run tests for a specific module
+uv run pytest tests/analysis/
+uv run pytest tests/instrumentation/
+uv run pytest tests/visualization/
+
+# Run a specific test file
+uv run pytest tests/analysis/test_discovery.py
+
+# Run tests matching a keyword
+uv run pytest -k "discovery"
+
+# Run with verbose output
+uv run pytest -v
+```
+
+All tests pass (44 tests across instrumentation, analysis, and visualization layers).
+
+## XES Event Log Format
+
+Events are stored in XES (eXtensible Event Stream) format with the following attribute mapping:
+
+| Concept | XES Attribute | Example |
+|---------|---------------|---------|
+| Invocation ID | `case:concept:name` | `"inv-abc123"` |
+| Activity | `concept:name` | `"tool:search"`, `"llm:gemini-2.0"` |
+| Completion time | `time:timestamp` | ISO datetime |
+| Start time | `strobe:start_time` | ISO datetime |
+| Duration | `strobe:duration_s` | `1.23` |
+| Tool arguments | `strobe:tool_args` | JSON string |
+| Tool result | `strobe:tool_result` | JSON string |
+| Model name | `strobe:model_name` | `"gemini-2.0-flash"` |
+| Input tokens | `strobe:input_tokens` | Integer count |
+| Output tokens | `strobe:output_tokens` | Integer count |
+
+## Supported Frameworks
+
+Currently supports:
+- Google AI Agent Development Kit (ADK)
+
+## Dependencies
+
+- **pm4py** >= 2.7.0 — Process mining algorithms
+- **pandas** >= 2.0.0 — Data manipulation
+- **networkx** — Graph algorithms
+- **plotly** >= 5.18.0 — Interactive visualizations
+- **streamlit** >= 1.32.0 — Dashboard UI
+- **google-adk** >= 1.0.0 — Agent framework
+
+## Contributing
+
+Contributions are welcome! Please:
+1. Write tests for any new functionality
+2. Run `uv run pytest` to ensure tests pass
+3. Follow existing code style and patterns
+
+## License
+
+(Add your license here)
+
+## Resources
+
+- [Process Mining Overview](https://en.wikipedia.org/wiki/Process_mining)
+- [Petri Nets](https://en.wikipedia.org/wiki/Petri_net)
+- [XES Standard](http://www.xes-standard.org/)
+- [pm4py Documentation](https://pm4py.fit.fraunhofer.de/)

strobe-0.0.1/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "strobe"
+dynamic = ["version"]
+description = "Process Mining & Agent Instrumentation for AI Agent Frameworks"
+requires-python = ">=3.13"
+dependencies = [
+    "google-adk>=1.0.0",
+    "pm4py>=2.7.0",
+    "pandas>=2.0.0",
+    "streamlit>=1.32.0",
+    "plotly>=5.18.0",
+]
+
+[dependency-groups]
+test = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.23.0",
+]
+dev = [
+    "ruff==0.15.4",
+    "mypy==1.19.1",
+    "pre-commit==4.5.1",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "strobe/_version.py"
+
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+
+[tool.ruff]
+extend-exclude = ["strobe/_version.py"]

strobe-0.0.1/strobe/__init__.py

@@ -0,0 +1,26 @@
+try:
+    from strobe._version import __version__
+except ImportError:
+    __version__ = "0.0.1.dev0"
+
+from strobe.analysis import (
+    activity_statistics,
+    check_conformance,
+    discover_dfg,
+    discover_process_model,
+    throughput_times,
+)
+from strobe.instrumentation import EventLog, StrobePlugin
+from strobe.visualization import launch_dashboard
+
+__all__ = [
+    "__version__",
+    "StrobePlugin",
+    "EventLog",
+    "discover_dfg",
+    "discover_process_model",
+    "check_conformance",
+    "throughput_times",
+    "activity_statistics",
+    "launch_dashboard",
+]

strobe-0.0.1/strobe/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

strobe-0.0.1/strobe/analysis/__init__.py

@@ -0,0 +1,11 @@
+from .conformance import check_conformance
+from .discovery import discover_dfg, discover_process_model
+from .performance import activity_statistics, throughput_times
+
+__all__ = [
+    "discover_dfg",
+    "discover_process_model",
+    "check_conformance",
+    "throughput_times",
+    "activity_statistics",
+]

strobe-0.0.1/strobe/analysis/conformance.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import pandas as pd
+import pm4py
+
+
+def check_conformance(
+    df: pd.DataFrame,
+    net,
+    initial_marking,
+    final_marking,
+) -> dict[str, float]:
+    """Run token-based replay conformance checking.
+
+    Parameters
+    ----------
+    df:
+        pm4py-formatted event log DataFrame.
+    net, initial_marking, final_marking:
+        Petri net model (e.g. from :func:`~strobe.analysis.discover_process_model`).
+
+    Returns
+    -------
+    dict with keys ``fitness``, ``precision``, ``generalization``, ``simplicity``.
+    """
+    fitness = pm4py.fitness_token_based_replay(df, net, initial_marking, final_marking)
+    precision = pm4py.precision_token_based_replay(
+        df, net, initial_marking, final_marking
+    )
+    generalization = pm4py.generalization_tbr(df, net, initial_marking, final_marking)
+    simplicity = pm4py.simplicity_petri_net(net, initial_marking, final_marking)
+
+    return {
+        "fitness": fitness.get("average_trace_fitness", float("nan")),
+        "precision": float(precision),
+        "generalization": float(generalization),
+        "simplicity": float(simplicity),
+    }