╔═══════════════════════════════════════════════╗
║ ⚙ ─────────────────────────────────── ⚙ ║
║ ║
║ M E T A F L O W C L O C K W O R K ║
║ ║
║ ⚙ ─────────────────────────────────── ⚙ ║
╚═══════════════════════════════════════════════╝
self-executing tags · bounded recursion · spec-driven runs · append-only ledgers
Quickstart · Architecture · Prompt Assets · Roadmap · Contributing · Changelog
pip install metaflow-clockwork·import metaflow_clockwork·metaflow-clockworkPublic open-source package distributed as
metaflow-clockworkand imported asmetaflow_clockwork.Not affiliated with Netflix Metaflow or the
metaflowpackage on PyPI.
MetaFlow Clockwork is a deterministic local runtime for building and testing AI agents — with explicit tagged execution units, bounded recursive workflows, and replayable ledgers baked in.
Most agent frameworks optimize for speed of experimentation. MetaFlow Clockwork optimizes for clarity of execution.
{
"version": 1,
"run_id": "example_harmonics",
"tick_limit": 2,
"root_tags": [
{
"tag_type": "gear",
"functions": ["spawn_harmonics"]
}
]
}Built for teams who want to:
- Model behavior as explicit execution units — no magic, no hidden wiring
- Bound recursion deliberately — depth is a parameter, not a liability
- Validate runs before they execute — catch spec errors before a single tick fires
- Produce replayable, verifiable ledgers — every meaningful run leaves a trace
- Stay local-first — no broker, no daemon, no hidden orchestration layer
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ ⚙ MetaTag execution Deterministic units that describe and │
│ run behavior │
│ │
│ ⚙ ClockworkEngine Bounded recursive ticking with explicit │
│ depth control │
│ │
│ ⚙ Event sinks In-memory and append-only ledger │
│ backends │
│ │
│ ⚙ Run-spec validation Validate a spec before a single tick │
│ fires │
│ │
│ ⚙ Ledger tools Summary, replay, and verification │
│ │
│ ⚙ CLI validate · spec-validate · spec-run · │
│ ledger-verify │
│ │
│ ⚙ Prompt assets Hygiene, template, doctrine, and role │
│ contract examples │
│ │
└─────────────────────────────────────────────────────────────────────┘
pip install metaflow-clockworkFrom source / dev install
# Standard local install
pip install .
# Editable install
pip install -e .
# Build distribution artifacts
python -m pip install --upgrade build twine
rm -rf build dist metaflow_clockwork.egg-info
python -m build --sdist --wheel
python -m twine check dist/*from metaflow_clockwork import ClockworkEngine, MetaTag, MetaTagType, RecordingEventSink
sink = RecordingEventSink()
engine = ClockworkEngine(
event_sink=sink,
run_id="demo-run",
request_id="demo-request",
)
root = MetaTag(
tag_id="root-gear",
tag_type=MetaTagType.GEAR,
event_sink=sink,
)
def spawn_once(tag: MetaTag):
if tag.data.get("spawned"):
return []
tag.data["spawned"] = True
child = tag.spawn_child(MetaTagType.COG, tag_id="child-cog")
return [child] if child else []
root.add_function("spawn_once", spawn_once)
engine.add_root_gear(root)
summary = engine.tick()
print(summary)
print([event.kind for event in sink.events])# Smoke check
metaflow-clockwork validate --run-root /tmp/metaflow-runs
# Validate a run spec
metaflow-clockwork spec-validate ./examples/basic_harmonics.json
# Execute locally and verify the resulting ledger
metaflow-clockwork spec-run ./examples/basic_harmonics.json --run-root /tmp/metaflow-runs
metaflow-clockwork ledger-verify /tmp/metaflow-runs/example_harmonics
# Module invocation also works
python -m metaflow_clockwork spec-validate ./examples/basic_harmonics.jsonTip: To validate the installed wheel rather than checked-out source, run commands from outside the repo root and pass an absolute path to the spec.
MetaTag objects are the fundamental execution unit. They do not just describe behavior — they carry it. Each tag holds typed functions, spawnable children, and scoped data. Tags execute deterministically: same input, same output, every time.
The ClockworkEngine ticks through a tag tree with explicit depth control. Recursion is a deliberate design choice here, not a footgun — you set the bounds, the engine respects them, the ledger records exactly what happened.
Catch configuration errors before a single tick fires. A run spec defines everything needed to execute a workflow: tag graph, function bindings, depth limits. Validate it locally, share it, version it.
Every meaningful execution leaves a replayable trace. The ledger backend records events in append-only fashion — suitable for verification, debugging, and auditing. Replay a run exactly as it happened, or diff two runs side by side.
No broker. No daemon. No hidden mesh. MetaFlow Clockwork runs entirely on your machine. The only orchestration layer is the one you can read in the source.
╔══════════════════════════════════════════════════════════════════╗
║ ║
║ PROMPT HYGIENE FIRST ║
║ Keep instructions, contracts, and boundaries explicit. ║
║ ║
║ SELF-CONTAINED ║
║ Explicit inputs. Explicit local resources. ║
║ No hidden control plane. ║
║ ║
║ DETERMINISTIC ║
║ Same input → inspectable, repeatable behavior. ║
║ ║
║ BOUNDED RECURSION ║
║ Recursion is useful when deliberate and constrained. ║
║ ║
║ LEDGERED EXECUTION ║
║ Every meaningful run leaves a replayable trace. ║
║ ║
║ LOCAL-FIRST ║
║ No broker. No daemon. No hidden mesh to get started. ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
The public prompt and doctrine surface lives under prompts/.
| Asset | Description |
|---|---|
| Prompt Hygiene | Rules for keeping prompts explicit and bounded |
| Prompt Template v1 | Canonical template for MetaFlow-style prompts |
| Self-Contained Execution Doctrine | The core philosophy in full |
| Example role contract | Reference contract for a local runtime agent |
| Example prompt | A worked example |
These assets are public docs and contracts. They describe how MetaFlow work should be framed and bounded. They do not add a hidden runtime loader, broker, or second orchestration surface.
Legacy QRBT bridge names remain only as compatibility notices for migration. Live QRBT bridge execution is not part of the public package.
| Example | Description |
|---|---|
examples/basic_harmonics.json |
Minimal JSON run spec to validate and execute |
examples/basic_clockwork.py |
Python example wiring tags and the engine |
docs/quickstart.md |
Hands-on walkthrough from zero to ledger |
Run the same checks used during release hardening:
# Syntax check
python3 -m py_compile metaflow_clockwork/*.py tests/test_*.py examples/basic_clockwork.py
# Unit tests
python3 -m unittest discover -s tests -p 'test_*.py' -v
# Build check
python3 -m pip install --upgrade build twine
rm -rf build dist metaflow_clockwork.egg-info
python3 -m build --sdist --wheel
python3 -m twine check dist/*
# End-to-end spec run
metaflow-clockwork spec-validate ./examples/basic_harmonics.json
metaflow-clockwork spec-run ./examples/basic_harmonics.json --run-root /tmp/metaflow-runs
metaflow-clockwork ledger-verify /tmp/metaflow-runs/example_harmonics| Architecture | How the engine, tags, and ledgers fit together |
| Prompt Assets | Public prompt hygiene, doctrine, and role contract examples |
| Roadmap | Where the public package is headed |
| Contributing | How to contribute |
| Security | Reporting vulnerabilities |
| Support | Getting help |
| Trademarks | Trademark and branding notice |
| Code of Conduct | Community standards |
| Changelog | What changed |
Licensed under Apache 2.0. Trademark and branding guidance: TRADEMARKS.md.
╔═══════════════════════════════════════════════╗
║ ⚙ ─────────────────────────────────── ⚙ ║
║ ║
║ Build agent systems that are inspectable, ║
║ replayable, and auditable. ║
║ ║
║ ⚙ ─────────────────────────────────── ⚙ ║
╚═══════════════════════════════════════════════╝
MetaFlow Clockwork™ · Open-source runtime by SoulHash® · Apache 2.0
Branding rights are reserved. See TRADEMARKS.md.