agentic-flows 0.1.1

Governed execution and replay with auditable non-determinism

Agentic Flows

A deterministic, contract-first execution and replay framework — strict invariants, reproducible runs, and traceable outputs. Build audit-ready agent workflows with stable artifacts and replayable traces.

Non-determinism is explicitly declared, budgeted, classified, governed, and audited. Determinism is a policy decision, not a binary property.

v1 scope covers deterministic execution, replay, and contract verification for offline workflows; it is intended for research engineers and platform teams who need audit-grade runs, and it is not for interactive chat systems, autonomous agents, or low-latency production serving.

This system prioritizes replayability and auditability over convenience and speed.

At a glance: deterministic execution • invariant enforcement • replayable traces • CLI surface • structured telemetry
Quality: coverage floors enforced per module, benchmark regression gate active, docs linted and built in CI, no telemetry.

---

Table of Contents

• Why Agentic Flows?
• Try It in 20 Seconds
• Key Features
• Installation
• Quick Start
• Artifacts & Reproducibility
• API Surface
• Built-in Commands
• Tests & Quality
• Project Tree
• Docs & Resources
• Contributing
• License

---

Why Agentic Flows?

Most agent tooling optimizes for velocity. Agentic Flows prioritizes repeatability, traceability, and audit-ready execution:

• Determinism first for reliable experiments and CI validation.
• Invariant enforcement with fail-fast execution semantics.
• Replayable traces for deterministic verification.
• Clear boundaries between execution, retrieval, and verification.

---

Try It in 20 Seconds

pipx install agentic-flows  # Or: pip install agentic-flows
agentic-flows --help
agentic-flows run examples/boring/flow.json --policy examples/boring/policy.json --db-path /tmp/flows.duckdb

---

Key Features

• Deterministic execution — reproducible runs with explicit budgets.
• Contract-first design — schema and invariants enforced at boundaries.
• Replayable traces — audit-grade execution records.
• Structured telemetry — correlation IDs and traceable events.

---

Installation

Requires Python 3.11+.

# Isolated install (recommended)
pipx install agentic-flows

# Standard
pip install agentic-flows

Upgrade: pipx upgrade agentic-flows or pip install --upgrade agentic-flows.

---

Quick Start

# Discover commands/flags
agentic-flows --help

# Run a deterministic execution
agentic-flows run examples/boring/flow.json --policy examples/boring/policy.json --db-path /tmp/flows.duckdb

---

Artifacts & Reproducibility

Artifacts are immutable and hash-addressed. Replaying a run verifies hashes before returning outputs.

agentic-flows replay examples/boring/flow.json --policy examples/boring/policy.json --run-id <run_id> --tenant-id <tenant> --db-path /tmp/flows.duckdb

Docs: Execution Lifecycle · Invariants

---

API Surface

HTTP API is experimental and currently unimplemented.

Docs: API Overview · Schema

---

Built-in Commands

Command	Description	Example
run	Execute a flow	agentic-flows run examples/boring/flow.json --policy examples/boring/policy.json --db-path /tmp/flow.duckdb
replay	Replay a stored run	agentic-flows replay examples/boring/flow.json --policy examples/boring/policy.json --run-id <run_id> --tenant-id <tenant> --db-path /tmp/flow.duckdb
inspect run	Inspect a stored run	agentic-flows inspect run <run_id> --tenant-id <tenant> --db-path /tmp/flow.duckdb

Full surface: CLI Surface

---

Tests & Quality

• Coverage floors: enforced per module in CI.
• Benchmarks: regression gate on critical path.
• Docs: linted and built in CI.

Quick commands:

make test
make lint
make quality

Artifacts: Generated in CI; see GitHub Actions for logs and reports.

---

Project Tree

api/            # OpenAPI schemas
config/         # Lint/type/security configs
docs/           # MkDocs site
makefiles/      # Task modules (docs, test, lint, etc.)
scripts/        # Helper scripts
src/agentic_flows/  # Runtime + CLI implementation
tests/          # unit / regression / e2e

---

Docs & Resources

• Overview: Why agentic-flows exists · Mental model · Minimal run · Relationship to agentic-proteins · Audience
• Concepts: Concepts index · Determinism · Failures
• Execution: Failure paths
• Site: https://bijux.github.io/agentic-flows/
• Changelog: https://github.com/bijux/agentic-flows/blob/main/CHANGELOG.md
• Repository: https://github.com/bijux/agentic-flows
• Issues: https://github.com/bijux/agentic-flows/issues
• Security (private reports): https://github.com/bijux/agentic-flows/security/advisories/new
• Artifacts: https://bijux.github.io/agentic-flows/artifacts/

---

Contributing

Welcome. See CONTRIBUTING.md for setup and test guidance.

---

License

Apache-2.0 — see LICENSE. © 2025 Bijan Mousavi.

---

This system is designed for auditability and replay, not exploratory or interactive use.

Non-goals

• Automatic agent self-improvement or learning

Publishing status

Current maturity: experimental research framework. v0.x carries no backward compatibility guarantees; schema compatibility is the only API guarantee. CLI output formatting and observability summaries may change without notice. Internal execution and verification APIs are not stable. Production usage should gate on strict determinism and explicit contracts.

Changelog

All notable changes to agentic-flows are documented here.
This project adheres to Semantic Versioning and the
Keep a Changelog format.

[Unreleased]

Added

• (add new entries via fragments in changelog.d/)

Changed

• (add here)

Fixed

• (add here)

---

[0.1.0] – 2025-01-21

Added

• Core runtime
  • Deterministic execution lifecycle with planning, execution, and finalization phases.
  • Execution modes: plan, dry-run, live, observe, and unsafe.
  • Strict determinism guardrails with explicit seed and environment fingerprints.
• Non-determinism governance
  • Declared non-determinism intent model and policy validation.
  • Entropy budgeting with enforcement, exhaustion semantics, and replay analysis.
  • Determinism profiles with structured replay metadata.
• Replay and audit
  • Replay modes (strict/bounded/observational) and acceptability classifications.
  • Trace diffing, replay envelopes, and deterministic replay validation.
  • Observability capture for events, artifacts, evidence, and entropy usage.
• Persistence
  • DuckDB execution store with schema contract enforcement and migrations.
  • Execution schema, replay envelopes, checkpoints, and trace storage.
• CLI + API surface
  • CLI commands for planning, running, replaying, inspecting, and diffing runs.
  • OpenAPI schema for the HTTP surface with schema hash stability checks.
• Policies and verification
  • Verification policy and arbitration plumbing for reasoning and evidence checks.
  • Failure taxonomy with deterministic error classes.
• Docs and examples
  • Determinism/non-determinism contract docs and storage model guidance.
  • Examples for deterministic and replay behavior.
• Quality gates
  • Makefile orchestration for tests, linting, docs, API checks, SBOM, and citation outputs.