open-agent-traces 0.1.0__tar.gz

open_agent_traces-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Type check
+        run: uv run mypy src
+
+      - name: Test
+        run: uv run pytest tests/ -v --tb=short

open_agent_traces-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,73 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Type check
+        run: uv run mypy src
+
+      - name: Test
+        run: uv run pytest tests/ -v --tb=short
+
+  publish-testpypi:
+    needs: test
+    if: contains(github.ref_name, 'rc') || contains(github.ref_name, 'dev')
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: test
+    if: "!contains(github.ref_name, 'rc') && !contains(github.ref_name, 'dev')"
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

open_agent_traces-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# macOS
+.DS_Store
+
+# Claude/superpowers
+docs/superpowers/

open_agent_traces-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

open_agent_traces-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Julien Simon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

open_agent_traces-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: open-agent-traces
+Version: 0.1.0
+Summary: Mock OCEL 2.0 event log generator for LangChain multi-agent runs
+Project-URL: Homepage, https://github.com/juliensimon/ocel-generator
+Project-URL: Documentation, https://github.com/juliensimon/ocel-generator/tree/main/docs
+Project-URL: Repository, https://github.com/juliensimon/ocel-generator
+Project-URL: Issues, https://github.com/juliensimon/ocel-generator/issues
+Project-URL: Dataset, https://huggingface.co/datasets/juliensimon/open-agent-traces
+Author-email: Julien Simon <julien@arcee.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-traces,ai-agents,anomaly-detection,langchain,llm,multi-agent,observability,ocel,process-mining,synthetic-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing :: Traffic Generation
+Requires-Python: >=3.11
+Requires-Dist: faker>=24.0
+Requires-Dist: huggingface-hub>=0.20
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: openai>=1.0
+Requires-Dist: pyarrow>=15.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: conformance
+Requires-Dist: pm4py>=2.7; extra == 'conformance'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ocelgen — Open Agent Traces Dataset Generator
+
+Generate realistic multi-agent workflow trace datasets with LLM-enriched content. Built for the AI agent ecosystem.
+
+[![Dataset on HF](https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-open--agent--traces-yellow)](https://huggingface.co/datasets/juliensimon/open-agent-traces)
+[![PyPI](https://img.shields.io/pypi/v/open-agent-traces)](https://pypi.org/project/open-agent-traces/)
+[![CI](https://github.com/juliensimon/ocel-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/juliensimon/ocel-generator/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://python.org)
+[![OCEL 2.0](https://img.shields.io/badge/OCEL-2.0-orange.svg)](https://www.ocel-standard.org/)
+[![OpenAI Compatible](https://img.shields.io/badge/API-OpenAI%20Compatible-lightgrey.svg)](docs/user-guide.md#model-and-endpoint-configuration)
+
+![Parallel workflow trace — market research domain](docs/parallel-workflow-example.png)
+
+## The problem
+
+Real agent traces are scarce. Production multi-agent systems generate rich execution data — LLM prompts, tool calls, agent reasoning, handoff messages — but these traces are proprietary and rarely shared. Teams building agent observability, evaluation, and debugging tools lack open datasets to develop against.
+
+## The solution
+
+ocelgen generates **structurally valid, semantically rich** agent traces that look and feel like real multi-agent executions:
+
+- **Full trace content** — LLM prompts and completions, tool call inputs/outputs, agent reasoning, inter-agent messages
+- **10 enterprise domains** — customer support, code review, incident response, financial analysis, and 6 more (plus custom domains via YAML)
+- **3 workflow patterns** — sequential, supervisor/worker, parallel fan-out/fan-in
+- **Labeled deviations** — 10 types of anomalies (wrong tools, skipped steps, timeouts) with ground-truth annotations
+- **OCEL 2.0 standard** — compatible with process mining tools (PM4Py, Celonis)
+- **Any LLM backend** — OpenRouter, OpenAI, Anthropic, local models via OpenAI-compatible API
+
+## Quick start
+
+```bash
+pip install open-agent-traces
+```
+
+### Development setup
+
+```bash
+git clone https://github.com/juliensimon/ocel-generator.git && cd ocel-generator
+uv sync
+```
+
+### LLM setup
+
+Enrichment requires an OpenAI-compatible endpoint. Pick one:
+
+**Cloud (OpenRouter, OpenAI, etc.)**
+```bash
+export OPENAI_API_KEY="your-key"
+# Default: OpenRouter with Gemini Flash. Override with --model:
+ocelgen enrich output.jsonocel -d customer-support-triage --model anthropic/claude-sonnet-4
+```
+
+**Local (llama.cpp, Ollama, vLLM, etc.)**
+```bash
+# Example: start llama.cpp with auto-download from Hugging Face
+llama-server -hfr unsloth/Qwen3-30B-A3B-GGUF:Q6_K -ngl 99 -c 4096
+
+# Point ocelgen at the local endpoint (no API key needed)
+ocelgen enrich output.jsonocel -d customer-support-triage \
+  --model unsloth/Qwen3-30B-A3B-GGUF:Q6_K \
+  --base-url http://localhost:8080/v1
+```
+
+### Generate and enrich
+
+```bash
+# Generate traces
+ocelgen generate --pattern sequential --runs 50 --noise 0.2
+
+# Enrich with LLM-generated content
+ocelgen enrich output.jsonocel --domain customer-support-triage
+
+# Or run the full pipeline (generate + enrich + upload to HF)
+ocelgen pipeline --domain customer-support-triage --namespace your-hf-username
+
+# Use custom domains defined in YAML
+ocelgen pipeline --domain my-domain --config domains.yaml --namespace your-hf-username
+```
+
+## Use the pre-built dataset
+
+Skip generation — load the dataset directly from Hugging Face:
+
+```python
+from datasets import load_dataset
+
+ds = load_dataset("juliensimon/open-agent-traces", "incident-response")
+
+for event in ds["train"]:
+    if event["run_id"] == "run-0000":
+        print(f"{event['event_type']:25s} | {event['agent_role']:12s} | {event['reasoning'][:60] if event['reasoning'] else ''}")
+```
+
+10 domains available: `customer-support-triage` · `code-review-pipeline` · `market-research` · `legal-document-analysis` · `data-pipeline-debugging` · `content-generation` · `financial-analysis` · `incident-response` · `academic-paper-review` · `ecommerce-product-enrichment`
+
+## Who is this for?
+
+- **Agent observability teams** — build dashboards with realistic trace data (timestamps, token counts, costs)
+- **ML researchers** — train anomaly detectors on labeled conformant vs deviant traces
+- **Process mining researchers** — apply OCEL 2.0 conformance checking to agent workflows
+- **Agent framework developers** — test LangGraph, CrewAI, AutoGen, Smolagents against realistic traces
+- **Evaluation teams** — benchmark agent reasoning quality across domains and architectures
+
+## Documentation
+
+- **[Quick Start](docs/quickstart.md)** — first dataset in 5 minutes
+- **[User Guide](docs/user-guide.md)** — CLI reference, patterns, domains, custom YAML config, model configuration
+- **[Dataset on Hugging Face](https://huggingface.co/datasets/juliensimon/open-agent-traces)** — 17,000+ events, ready to use
+
+## License
+
+MIT

open_agent_traces-0.1.0/README.md

@@ -0,0 +1,113 @@
+# ocelgen — Open Agent Traces Dataset Generator
+
+Generate realistic multi-agent workflow trace datasets with LLM-enriched content. Built for the AI agent ecosystem.
+
+[![Dataset on HF](https://img.shields.io/badge/%F0%9F%A4%97%20Dataset-open--agent--traces-yellow)](https://huggingface.co/datasets/juliensimon/open-agent-traces)
+[![PyPI](https://img.shields.io/pypi/v/open-agent-traces)](https://pypi.org/project/open-agent-traces/)
+[![CI](https://github.com/juliensimon/ocel-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/juliensimon/ocel-generator/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://python.org)
+[![OCEL 2.0](https://img.shields.io/badge/OCEL-2.0-orange.svg)](https://www.ocel-standard.org/)
+[![OpenAI Compatible](https://img.shields.io/badge/API-OpenAI%20Compatible-lightgrey.svg)](docs/user-guide.md#model-and-endpoint-configuration)
+
+![Parallel workflow trace — market research domain](docs/parallel-workflow-example.png)
+
+## The problem
+
+Real agent traces are scarce. Production multi-agent systems generate rich execution data — LLM prompts, tool calls, agent reasoning, handoff messages — but these traces are proprietary and rarely shared. Teams building agent observability, evaluation, and debugging tools lack open datasets to develop against.
+
+## The solution
+
+ocelgen generates **structurally valid, semantically rich** agent traces that look and feel like real multi-agent executions:
+
+- **Full trace content** — LLM prompts and completions, tool call inputs/outputs, agent reasoning, inter-agent messages
+- **10 enterprise domains** — customer support, code review, incident response, financial analysis, and 6 more (plus custom domains via YAML)
+- **3 workflow patterns** — sequential, supervisor/worker, parallel fan-out/fan-in
+- **Labeled deviations** — 10 types of anomalies (wrong tools, skipped steps, timeouts) with ground-truth annotations
+- **OCEL 2.0 standard** — compatible with process mining tools (PM4Py, Celonis)
+- **Any LLM backend** — OpenRouter, OpenAI, Anthropic, local models via OpenAI-compatible API
+
+## Quick start
+
+```bash
+pip install open-agent-traces
+```
+
+### Development setup
+
+```bash
+git clone https://github.com/juliensimon/ocel-generator.git && cd ocel-generator
+uv sync
+```
+
+### LLM setup
+
+Enrichment requires an OpenAI-compatible endpoint. Pick one:
+
+**Cloud (OpenRouter, OpenAI, etc.)**
+```bash
+export OPENAI_API_KEY="your-key"
+# Default: OpenRouter with Gemini Flash. Override with --model:
+ocelgen enrich output.jsonocel -d customer-support-triage --model anthropic/claude-sonnet-4
+```
+
+**Local (llama.cpp, Ollama, vLLM, etc.)**
+```bash
+# Example: start llama.cpp with auto-download from Hugging Face
+llama-server -hfr unsloth/Qwen3-30B-A3B-GGUF:Q6_K -ngl 99 -c 4096
+
+# Point ocelgen at the local endpoint (no API key needed)
+ocelgen enrich output.jsonocel -d customer-support-triage \
+  --model unsloth/Qwen3-30B-A3B-GGUF:Q6_K \
+  --base-url http://localhost:8080/v1
+```
+
+### Generate and enrich
+
+```bash
+# Generate traces
+ocelgen generate --pattern sequential --runs 50 --noise 0.2
+
+# Enrich with LLM-generated content
+ocelgen enrich output.jsonocel --domain customer-support-triage
+
+# Or run the full pipeline (generate + enrich + upload to HF)
+ocelgen pipeline --domain customer-support-triage --namespace your-hf-username
+
+# Use custom domains defined in YAML
+ocelgen pipeline --domain my-domain --config domains.yaml --namespace your-hf-username
+```
+
+## Use the pre-built dataset
+
+Skip generation — load the dataset directly from Hugging Face:
+
+```python
+from datasets import load_dataset
+
+ds = load_dataset("juliensimon/open-agent-traces", "incident-response")
+
+for event in ds["train"]:
+    if event["run_id"] == "run-0000":
+        print(f"{event['event_type']:25s} | {event['agent_role']:12s} | {event['reasoning'][:60] if event['reasoning'] else ''}")
+```
+
+10 domains available: `customer-support-triage` · `code-review-pipeline` · `market-research` · `legal-document-analysis` · `data-pipeline-debugging` · `content-generation` · `financial-analysis` · `incident-response` · `academic-paper-review` · `ecommerce-product-enrichment`
+
+## Who is this for?
+
+- **Agent observability teams** — build dashboards with realistic trace data (timestamps, token counts, costs)
+- **ML researchers** — train anomaly detectors on labeled conformant vs deviant traces
+- **Process mining researchers** — apply OCEL 2.0 conformance checking to agent workflows
+- **Agent framework developers** — test LangGraph, CrewAI, AutoGen, Smolagents against realistic traces
+- **Evaluation teams** — benchmark agent reasoning quality across domains and architectures
+
+## Documentation
+
+- **[Quick Start](docs/quickstart.md)** — first dataset in 5 minutes
+- **[User Guide](docs/user-guide.md)** — CLI reference, patterns, domains, custom YAML config, model configuration
+- **[Dataset on Hugging Face](https://huggingface.co/datasets/juliensimon/open-agent-traces)** — 17,000+ events, ready to use
+
+## License
+
+MIT

open_agent_traces-0.1.0/docs/announcements/linkedin.md

@@ -0,0 +1,18 @@
+Real agent traces are scarce. If you're building observability, evaluation, or debugging tools for multi-agent systems, you know the pain — production traces are proprietary, and toy examples don't cut it.
+
+I built open-agent-traces to fix this. It generates structurally valid, semantically rich execution traces that look and feel like real multi-agent workflows:
+
+- 10 enterprise domains (customer support, code review, incident response, financial analysis...)
+- 3 workflow patterns (sequential, supervisor/worker, parallel fan-out)
+- LLM-enriched content — real prompts, completions, tool calls, agent reasoning
+- Labeled anomalies for training detectors (wrong tools, skipped steps, timeouts)
+- OCEL 2.0 standard — works with PM4Py, Celonis, and other process mining tools
+
+pip install open-agent-traces
+
+Pre-built dataset on Hugging Face: https://huggingface.co/datasets/juliensimon/open-agent-traces
+Code: https://github.com/juliensimon/ocel-generator
+
+MIT licensed. Contributions welcome.
+
+#AI #agents #opensource #processmining

open_agent_traces-0.1.0/docs/announcements/x.md

@@ -0,0 +1,7 @@
+No open trace data for multi-agent systems? I built a fix.
+
+open-agent-traces generates realistic LLM-enriched execution traces — 10 domains, 3 workflow patterns, labeled anomalies, OCEL 2.0 compliant.
+
+pip install open-agent-traces
+
+https://github.com/juliensimon/ocel-generator

open_agent_traces-0.1.0/docs/quickstart.md

@@ -0,0 +1,117 @@
+# Quick Start
+
+Generate your first synthetic agent traces dataset in under 5 minutes.
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- An [OpenRouter](https://openrouter.ai) API key (for LLM enrichment)
+
+## Installation
+
+```bash
+git clone https://github.com/juliensimon/ocel-generator.git
+cd ocel-generator
+uv sync
+```
+
+## Step 1: Generate structural traces
+
+Generate 20 sequential workflow runs with 20% noise (deviations):
+
+```bash
+ocelgen generate --pattern sequential --runs 20 --noise 0.2 --seed 42
+```
+
+This creates three files:
+- `output.jsonocel` — the OCEL 2.0 event log
+- `normative_model.json` — the expected workflow template
+- `manifest.json` — generation metadata and injected deviations
+
+## Step 2: Enrich with LLM content
+
+Set your OpenRouter API key:
+
+```bash
+export OPENAI_API_KEY="sk-or-v1-your-key-here"
+```
+
+Enrich the traces with realistic prompts, completions, and tool I/O:
+
+```bash
+ocelgen enrich output.jsonocel --domain customer-support-triage
+```
+
+This produces `enriched-output.jsonocel` with LLM-generated content for each agent step.
+
+## Step 3: Explore the data
+
+```python
+import json
+
+with open("enriched-output.jsonocel") as f:
+    log = json.load(f)
+
+# See what's inside
+print(f"Events: {len(log['events'])}")
+print(f"Objects: {len(log['objects'])}")
+
+# Look at an enriched LLM call
+for obj in log["objects"]:
+    if obj["type"] == "llm_call":
+        attrs = {a["name"]: a["value"] for a in obj["attributes"]}
+        if attrs.get("prompt"):
+            print(f"\nPrompt: {attrs['prompt'][:200]}")
+            print(f"Completion: {attrs['completion'][:200]}")
+            break
+```
+
+## Step 4: Upload to Hugging Face (optional)
+
+```bash
+ocelgen pipeline --domain customer-support-triage --namespace your-hf-username
+```
+
+This runs the full pipeline (generate + enrich + flatten + upload) and creates a dataset on HF Hub.
+
+## Step 5: Use custom domains (optional)
+
+Define your own domains in a YAML file:
+
+```yaml
+# my-domains.yaml
+domains:
+  - name: "hr-onboarding"
+    description: "HR onboarding: collect docs, run checks, provision access"
+    pattern: "sequential"
+    runs: 30
+    noise: 0.15
+    seed: 50001
+    user_queries:
+      - "New hire John Smith starting March 15 as Senior Engineer"
+      - "Onboard contractor Maria Garcia for 6-month engagement"
+    agent_personas:
+      researcher: "You are an HR coordinator collecting new hire documentation"
+      analyst: "You are a compliance officer verifying background checks"
+      summarizer: "You are an IT provisioner setting up accounts and access"
+    tool_descriptions:
+      web_search: "Search HR knowledge base for onboarding checklists"
+      file_reader: "Read employee records and compliance documents"
+```
+
+Then pass it with `--config`:
+
+```bash
+ocelgen enrich output.jsonocel --domain hr-onboarding --config my-domains.yaml
+ocelgen pipeline --domain hr-onboarding --config my-domains.yaml --namespace your-hf-username
+```
+
+Custom domains merge with the 10 built-ins. To override a built-in, use the same `name`.
+
+## Next steps
+
+- Read the [User Guide](user-guide.md) for detailed configuration options
+- Try different [workflow patterns](user-guide.md#workflow-patterns): `sequential`, `supervisor`, `parallel`
+- Explore all 10 [built-in domains](user-guide.md#domains) or [define your own](user-guide.md#custom-domains)
+- Use the [pre-built dataset](https://huggingface.co/datasets/juliensimon/open-agent-traces) directly