Skip to main content

markov-ci

Markov-planned, guardrailed CI/CD — governance for agentic pipelines.

License: Apache 2.0 PyPI Python 3.11 | 3.12 | 3.13 Status: pre-1.0 Code style: ruff Types: mypy strict Docs: mkdocs PRs welcome

markov-ci models an agentic CI/CD pipeline as an absorbing Markov chain — a small state space, measured transition probabilities, and three designed terminal outcomes — instead of a deterministic DAG governed by brittle if/else retry rules. The chain is the planning model (it forecasts cost and attempts and sizes the caps); at runtime a bounded governor admits, checks and stops the repair loop — it does not sample the chain. From the model markov-ci forecasts what your agents will cost, governs them with hard limits at runtime, and learns from its own telemetry (ADR-0014).

Status: pre-1.0. v0.1.1 ("Trust") is the current release — the security and correctness fixes from the v0.1.1 review. Upgrade from v0.1.0: that release ran the harness prompt through a shell (a remote-code-execution path); v0.1.1 makes harness invocation argv-only (ADR-0016). See the CHANGELOG and SECURITY.md. The public API is not yet stable.

The problem

CI/CD stopped being deterministic, for two reasons:

  1. Ephemeral infrastructure — distributed suites, cloud runners, spot interruptions: identical commits now flake.
  2. AI agents in the loop — agents triage, patch, and refactor inside pipelines, with probabilistic behavior (fix ~75% / loop ~15% / regress ~10% is a commonly cited ballpark, not a markov-ci measurement).

Governed by rigid rules, probabilistic agents give you one of two disasters: guardrails so strict the agent never helps, or runaway retries that burn tokens, hang PRs, and silently weaken your tests. And nobody can answer "should the agent get 2 retries or 10?" with a number.

What it does

Capability You get
📊 Forecast Expected agent attempts, token spend, and outcome probabilities per failure category — before you enable anything. N = (I−Q)⁻¹ · B = N·R · t = N·1 · C = N·c
🛡️ Govern Budget, attempt-cap, and confidence gates; enforced write allowlists; test-weakening hard-stopped; patches isolated to ai-fix/* branches; humans always merge
🔁 Learn One versioned JSONL event per state hop; the transition matrix recomputes from your own telemetry, per failure category and per agent harness

Why it cannot run away: attempt caps remove loop-back edges at assembly time, so every chain markov-ci can execute is absorbing by construction — after the cap Q is nilpotent, so absorption is a property of the model. The runtime stops via its attempt counter plus per-call timeouts (a hung child is killed on timeout), so a run is bounded even under adversarial probabilities.

⚠️ Security notice (v0.1.1). For pull_request events from untrusted authors (forks), enable container isolation (container: python:3.12-slim, or the --container-image flag) so PR code cannot reach host credentials; it is the recommended default for fork PRs. Without it, do not set adapter: harness on untrusted forks — use adapter: simulated. See SECURITY.md and ADR-0013.

Quick start

The commands below are the v0.1.1 contract. Docs-are-tests: CI runs them verbatim (see docs/quick-start.md, executed by tests/unit/docs/test_docs_are_tests.py). Install v0.1.1 or later — v0.1.0 carries the harness shell-injection advisory (ADR-0016, GHSA-5jj3-gcw8-pm5g).

pip install -U "markov-ci>=0.1.1"        # PyPI; 3.11–3.13
# until 0.1.1 is on PyPI, install the release tag:
# pip install "markov-ci @ git+https://github.com/deghosal-2026/markov-ci@v0.1.1"

markov-ci analyze                                   # zero-config: prints the worked example
markov-ci analyze --category unit_assertion         # per-attempt decay + expected cost

# the offline demos live in the repo:
git clone https://github.com/deghosal-2026/markov-ci && cd markov-ci
markov-ci run examples/01-lint-error/config.yaml \
    --junit examples/01-lint-error/report.xml \
    --repo examples/01-lint-error/repo --seed 42

markov-ci is published on PyPI as markov-ci (Trusted Publishing, PEP 740 build provenance). No API keys, no network — the default agent is a seeded, offline simulator. See the quick start for the full five-minute path.

How it works

A pipeline becomes a chain of decision states with three absorbing outcomes:

s0 verify ─▶ s1 triage ─▶ s2 agent ─▶ s3 worktree validation ─▶ s4 regression ─▶ a1 ready-for-review
                              ▲             │                              ▲
                              └──── loop ────┘        escalate ─▶ a2 · budget ─▶ a3
                         (attempt index in the state: s2#1, s3#2, …)

Per-attempt decay is modeled by step-augmented states (s2#1, s2#2, …), which keeps the chain genuinely Markov so the closed-form math stays exact. The engine evaluates gates strictly in order — budget → attempt cap → confidence — and every hop emits a versioned telemetry event. Read the math, derived or the architecture.

Documentation

Everything below also builds as a site — run mkdocs serve.

Start here

Guides

Reference & explanations

How this project is specified

Project files

Roadmap

Release Theme Highlights
v0.1.0 Absorption Shipped: math core · policy engine · triage · simulated, harness and local-LLM agents · guardrails · runtime · telemetry + recompute · queueing (Erlang-C + DES) · CLI (validate/analyze/run/simulate/queue/recompute) · composite GitHub Action · offline demos 01–07
v0.1.1 Trust Shipped (PyPI): argv-only harness (ADR-0016) · diff-derived guardrails · worktree validation + opt-in container isolation · hard budgets (remaining-timeout → a3) · patch delivery (--output-patch, --publish) · model/runtime honesty (analyze from s1) · hardened test suite · field-test evidence
v0.2.0 Capacity & reach Live harness verification (Claude Code / OpenCode / Aider) · MCP tool surface · drift/windowing
v0.3.0 Live operations MCP governance server · currency cost model · drift alerts · community harness templates

Full ticket-level breakdown: v0.1.1 WBS · v0.1.0 WBS.

What it is not

Not an agent harness (it governs harnesses) · not auto-merge (a1 is always a human decision) · not a CI replacement (it plugs into GitHub Actions / GitLab / Jenkins) · not a dashboard (CLI + JSON events) · no telemetry leaves your machine.

Contributing

Contributions are welcome once the repository goes public. Start with CONTRIBUTING.md and the ADRs — every design decision and its rationale is recorded there.

License

Apache-2.0.

Metadata

Release files for markov-ci 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for markov-ci 0.1.1
File Size Uploaded Provenance Actions
markov_ci-0.1.1.tar.gz 219.9 kB Without provenance Details for markov_ci-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for markov-ci 0.1.1
File Interpreter ABI Platform Actions
markov_ci-0.1.1-py3-none-any.whl Python 3 none any Details for markov_ci-0.1.1-py3-none-any.whl

Total release size: 296.6 kB

Release files / markov_ci-0.1.1.tar.gz

Download URL markov_ci-0.1.1.tar.gz
Size 219.9 kB
Tags Source
SHA-256 checksum
How to use checksums
14f7051192ab3ad08ed51b45a435c4f8bc4b1091ff7ed544660d6f8e2f00c53d
BLAKE2b-256 checksum
How to use checksums
b443d1f2bce5c7855e69228d4f365f75dc734954d60e673a1f3918e298193713
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Release files / markov_ci-0.1.1-py3-none-any.whl

Download URL markov_ci-0.1.1-py3-none-any.whl
Size 76.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b82a8707a35095e03a3f7b8ea889b3626308c1e27480bbd0270cd526422c486f
BLAKE2b-256 checksum
How to use checksums
88e3d36c2b6f18083fe51e0be3ec7c8e5d40c07311a0587923526c4c7da2dd2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.5

Security for markov-ci 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page