Metadata-Version: 2.4
Name: markovian
Version: 1.2.1
Summary: Python SDK for the Markovian Protocol: verifiable provenance for agent and model outputs. Commit, resolve, and trace, on a Bitcoin-anchored, ZK-verified chain.
Author-email: Markovian Protocol <hello@quantsynth.net>
License: MIT
Project-URL: Homepage, https://markovianprotocol.com
Project-URL: Documentation, https://markovianprotocol.com/build
Project-URL: Source, https://github.com/MarkovianProtocol/markovian-protocol
Project-URL: Explorer, https://chain.quantsynth.net
Keywords: markovian,oracle,zk,zero-knowledge,blockchain,market-regime,defi,prediction-markets,markov,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Requires-Dist: numpy>=1.20
Requires-Dist: py_ecc>=6.0
Dynamic: license-file

# markovian

Python SDK for the [Markovian Protocol](https://markovianprotocol.com). Three primitives for verifiable provenance, on a Bitcoin-anchored chain:

- **COMMIT** — prove it existed. Commit any record, get an unforgeable, publicly verifiable proof.
- **RESOLVE** — prove it was right. Read the chain's ZK-proven regime state and verify it, no oracle.
- **TRACE** — prove where it came from. Walk a stamp's lineage across protocols.

Keyless to start. No account, no API key.

```bash
pip install markovian
```

## First swing: COMMIT and verify, no setup

Write any JSON record to the chain. No wallet, no API key. The protocol mints an ephemeral committer and the stamp is free. The result is unforgeable, publicly verifiable, and Bitcoin-anchored.

```python
from markovian import MarkovianClient

client = MarkovianClient()
proof = client.stamp({"event": "audit-2026"})    # no wallet, no key, free
print(proof["verify_url"])                        # anyone can check it, no trust in you
```

Verification needs no trust in the API. The ZK circuit runs client-side against a Merkle root:

```python
result = client.verify(proof["merkle_root"], local=True)
print(result["verified"], result.get("local_zk_verified"))
```

## RESOLVE: read the chain's verdict, not a price feed

Each block is a Markov state transition with a BN128 zero-knowledge proof verified on-chain, so the regime classification (ACCUMULATION, MARKUP, or DISTRIBUTION) is reproducible and cannot be forged by any single party. No external feed to manipulate.

```python
# Latest ZK-proven regime snapshot for liquid tickers
for r in client.latest():
    print(f"{r.ticker:<6} {r.regime:<14} {r.confidence*100:.1f}%")

# QQQ    DISTRIBUTION   61.3%
# SPY    DISTRIBUTION   67.8%
# GLD    DISTRIBUTION   99.0%

history = client.regime("QQQ", days=90)           # one ticker, over time
snap    = client.batch(["SPY", "QQQ", "GLD", "TLT"])
```

From the command line:

```bash
markovian latest
markovian regime QQQ 90
markovian tip
```

## TRACE: lineage across protocols

A stamp can reference another stamp, with the reference bound inside the committed bytes, so commitments and resolutions form one Bitcoin-anchored provenance graph. The SDK supports lineage directly: pass `derived_from` to `stamp()` to bind a record to its parents, and the edge is committed in-band. TRACE then walks the resulting graph and verifies every node and edge. Provenance, not truth: it returns a map, not a verdict.

```python
parent = client.stamp({"claim": "QQQ DISTRIBUTION at close"})
child  = client.stamp({"verdict": "PASS"}, derived_from=[parent])   # pass the prior stamp record
```

See the [TRACE docs](https://markovianprotocol.com/trace.html).

## Why it exists

Software increasingly acts on outputs no one can independently check: a model's classification, an agent's action, a settlement value. Markovian is a verification standard for those outputs. A producer commits a result, proves it was computed correctly, and traces where it came from, and any third party verifies all three with no trust in the producer.

Correctness is reproducible from `s_N = M^N x s`, where `M` is the protocol-published transition matrix and `s` derives deterministically from the previous block hash, with a ZK proof verified on-chain. It is a property anyone can recompute, not a claim to be believed.

Oracle manipulation is the sharpest example of what breaks without this. More than $400M has been lost to it since 2022, and every exploit shared one root cause: an external feed that could be skewed. A value derived by verifiable computation, rather than fed, removes that attack surface. It is one application of the standard, not the whole of it.

Trust becomes a commons, not a toll: verification is emitted by the chain, available to any party without account, fee, or permission.

## Tiers

| Tier       | Access                                  | Key |
|------------|-----------------------------------------|-----|
| Free       | Keyless COMMIT + verify, liquid tickers, 90-day window | None |
| Pro        | All tickers, full history, CSV export   | Required |
| Enterprise | All of Pro, plus inline ZK proofs       | Required |

Keys are issued at [markovianprotocol.com](https://markovianprotocol.com).

## API surface

- `stamp(data, wallet=None, derived_from=None)` — COMMIT a record (frictionless: no wallet needed); pass `derived_from` to bind lineage for TRACE
- `verify(merkle_root, local)` — verify a proof against the registry, optionally re-running the ZK circuit locally
- `faucet(wallet)` — claim test MKV
- `latest()` — current regime snapshot for liquid tickers
- `regime(ticker, days)` — regime history for one ticker
- `batch(tickers)` — snapshot across multiple tickers
- `catalog()` — available tickers and coverage
- `watch(tickers, callback)` — poll for regime transitions
- `tip()`, `block(height)`, `ledger()` — chain primitives

## Requirements

Python 3.8+, with `requests`, `numpy`, and `py_ecc` (installed automatically).

## Links

- Protocol: https://markovianprotocol.com
- Build docs: https://markovianprotocol.com/build
- Explorer: https://chain.quantsynth.net
- Source: https://github.com/MarkovianProtocol/markovian-protocol

MIT licensed.
