Skip to main content

markov-ci

Markov-governed, self-healing CI/CD — governance for agentic pipelines.

License: Apache 2.0 Python 3.11 | 3.12 | 3.13 Status: pre-alpha 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. From that model it forecasts what your agents will cost, governs them with hard limits at runtime, and learns from its own telemetry.

Status: pre-alpha. Private during initial development; intended for open-source release under Apache-2.0. The CLI, config, and telemetry contracts are specified and documented; implementation lands per the WBS.

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 typical).

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. Termination is a theorem, not a timeout — even under adversarial probabilities.

Quick start

The commands below are the v0.1.0 contract. Docs-are-tests: CI runs them verbatim (see docs/quick-start.md, executed by tests/unit/docs/test_docs_are_tests.py).

git clone https://github.com/deghosal-2026/markov-ci && cd markov-ci
pip install -e ".[dev]"

markov-ci analyze                                   # zero-config: prints the worked example
markov-ci analyze --category unit_assertion         # per-attempt decay + expected cost
markov-ci run examples/01-lint-error/config.yaml \
    --junit examples/01-lint-error/report.xml \
    --repo examples/01-lint-error/repo --seed 42

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 sandbox ─▶ 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 Math core · policy engine · triage · simulated agent · guardrails · runtime · telemetry · CLI · offline proof-suite demos 01–03, 06–07
v0.2.0 Capacity & reach GitHub Action · queueing (Erlang-C + DES) · simulate · recompute · harness adapters (Claude Code, OpenCode, Aider)
v0.3.0 Live operations MCP governance server · currency cost model · drift alerts · community harness templates

Full ticket-level breakdown: docs/WBS.md.

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.0

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.0
File Size Uploaded Provenance Actions
markov_ci-0.1.0.tar.gz 159.5 kB Without provenance Details for markov_ci-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 221.1 kB

Release files / markov_ci-0.1.0.tar.gz

Download URL markov_ci-0.1.0.tar.gz
Size 159.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1ff542c35909a12da52546fadd12ffc89149e691e75c293a9f27c6879b245a24
BLAKE2b-256 checksum
How to use checksums
24771f26b1786a6d491a09c31234f36621e6bf7104e245a7fd7a033006c441b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

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

Download URL markov_ci-0.1.0-py3-none-any.whl
Size 61.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6aa353c9af865385de45123b4286b418bc7ae22974ceddc9bb78c10fb5aaedf8
BLAKE2b-256 checksum
How to use checksums
d6ca24e4e983913f0f177bf10ea13f3a1a8b28806b183aaa3f57f72289bc2c5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for markov-ci 0.1.0

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.0 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