markovian 1.0.0__tar.gz

markovian-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markovian Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

markovian-1.0.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: markovian
+Version: 1.0.0
+Summary: Python SDK for the Markovian Protocol: verifiable market-regime data, on-chain ZK proofs, and STAMP commitment from a proof-of-intelligence Layer 1.
+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), a proof-of-intelligence Layer 1 that produces ZK-verified market-regime classifications and commits arbitrary data to an immutable, Bitcoin-anchored chain.
+
+```bash
+pip install markovian
+```
+
+## Why it exists
+
+More than $400M has been lost to oracle manipulation since 2022. Every exploit shared a root cause: an external price feed that could be skewed. The Markovian Protocol removes the feed. Each block is a Markov state transition, `s_N = M^N x s`, where `M` is the protocol-published transition matrix and `s` derives deterministically from the previous block hash. A BN128 zero-knowledge proof attesting to that computation is verified on-chain, so the output (a regime classification of ACCUMULATION, MARKUP, or DISTRIBUTION) is reproducible and cannot be forged by any single party.
+
+This package is the client for reading that data, verifying the proofs locally, and committing records to the chain.
+
+## Quickstart
+
+The free tier is keyless. No account, no API key.
+
+```python
+from markovian import MarkovianClient
+
+client = MarkovianClient()
+
+# 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%
+
+# Regime history for a single ticker
+history = client.regime("QQQ", days=90)
+
+# Snapshot across several tickers at once
+snap = client.batch(["SPY", "QQQ", "GLD", "TLT"])
+```
+
+From the command line:
+
+```bash
+markovian latest
+markovian regime QQQ 90
+markovian tip
+```
+
+## Verify a proof locally
+
+Verification requires no trust in the API. The ZK circuit runs client-side against a Merkle root.
+
+```python
+result = client.verify(merkle_root, local=True)
+print(result["verified"], result.get("local_zk_verified"))
+```
+
+## Commit data to the chain (STAMP)
+
+STAMP writes any JSON-serialisable record to the chain permanently. The result is unforgeable, publicly verifiable, and Bitcoin-anchored.
+
+```python
+client.faucet("my-wallet")                      # 100 free test MKV
+proof = client.stamp({"event": "audit-2026"}, wallet="my-wallet")
+print(proof["verify_url"])
+```
+
+## Tiers
+
+| Tier       | Access                                  | Key |
+|------------|-----------------------------------------|-----|
+| Free       | 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
+
+- `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
+- `verify(merkle_root, local)` — verify a proof against the registry, optionally re-running the ZK circuit locally
+- `stamp(data, wallet)` — commit a record to the chain
+- `faucet(wallet)` — claim test MKV
+- `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.

markovian-1.0.0/README.md

@@ -0,0 +1,99 @@
+# markovian
+
+Python SDK for the [Markovian Protocol](https://markovianprotocol.com), a proof-of-intelligence Layer 1 that produces ZK-verified market-regime classifications and commits arbitrary data to an immutable, Bitcoin-anchored chain.
+
+```bash
+pip install markovian
+```
+
+## Why it exists
+
+More than $400M has been lost to oracle manipulation since 2022. Every exploit shared a root cause: an external price feed that could be skewed. The Markovian Protocol removes the feed. Each block is a Markov state transition, `s_N = M^N x s`, where `M` is the protocol-published transition matrix and `s` derives deterministically from the previous block hash. A BN128 zero-knowledge proof attesting to that computation is verified on-chain, so the output (a regime classification of ACCUMULATION, MARKUP, or DISTRIBUTION) is reproducible and cannot be forged by any single party.
+
+This package is the client for reading that data, verifying the proofs locally, and committing records to the chain.
+
+## Quickstart
+
+The free tier is keyless. No account, no API key.
+
+```python
+from markovian import MarkovianClient
+
+client = MarkovianClient()
+
+# 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%
+
+# Regime history for a single ticker
+history = client.regime("QQQ", days=90)
+
+# Snapshot across several tickers at once
+snap = client.batch(["SPY", "QQQ", "GLD", "TLT"])
+```
+
+From the command line:
+
+```bash
+markovian latest
+markovian regime QQQ 90
+markovian tip
+```
+
+## Verify a proof locally
+
+Verification requires no trust in the API. The ZK circuit runs client-side against a Merkle root.
+
+```python
+result = client.verify(merkle_root, local=True)
+print(result["verified"], result.get("local_zk_verified"))
+```
+
+## Commit data to the chain (STAMP)
+
+STAMP writes any JSON-serialisable record to the chain permanently. The result is unforgeable, publicly verifiable, and Bitcoin-anchored.
+
+```python
+client.faucet("my-wallet")                      # 100 free test MKV
+proof = client.stamp({"event": "audit-2026"}, wallet="my-wallet")
+print(proof["verify_url"])
+```
+
+## Tiers
+
+| Tier       | Access                                  | Key |
+|------------|-----------------------------------------|-----|
+| Free       | 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
+
+- `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
+- `verify(merkle_root, local)` — verify a proof against the registry, optionally re-running the ZK circuit locally
+- `stamp(data, wallet)` — commit a record to the chain
+- `faucet(wallet)` — claim test MKV
+- `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.

markovian-1.0.0/markovian.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: markovian
+Version: 1.0.0
+Summary: Python SDK for the Markovian Protocol: verifiable market-regime data, on-chain ZK proofs, and STAMP commitment from a proof-of-intelligence Layer 1.
+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), a proof-of-intelligence Layer 1 that produces ZK-verified market-regime classifications and commits arbitrary data to an immutable, Bitcoin-anchored chain.
+
+```bash
+pip install markovian
+```
+
+## Why it exists
+
+More than $400M has been lost to oracle manipulation since 2022. Every exploit shared a root cause: an external price feed that could be skewed. The Markovian Protocol removes the feed. Each block is a Markov state transition, `s_N = M^N x s`, where `M` is the protocol-published transition matrix and `s` derives deterministically from the previous block hash. A BN128 zero-knowledge proof attesting to that computation is verified on-chain, so the output (a regime classification of ACCUMULATION, MARKUP, or DISTRIBUTION) is reproducible and cannot be forged by any single party.
+
+This package is the client for reading that data, verifying the proofs locally, and committing records to the chain.
+
+## Quickstart
+
+The free tier is keyless. No account, no API key.
+
+```python
+from markovian import MarkovianClient
+
+client = MarkovianClient()
+
+# 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%
+
+# Regime history for a single ticker
+history = client.regime("QQQ", days=90)
+
+# Snapshot across several tickers at once
+snap = client.batch(["SPY", "QQQ", "GLD", "TLT"])
+```
+
+From the command line:
+
+```bash
+markovian latest
+markovian regime QQQ 90
+markovian tip
+```
+
+## Verify a proof locally
+
+Verification requires no trust in the API. The ZK circuit runs client-side against a Merkle root.
+
+```python
+result = client.verify(merkle_root, local=True)
+print(result["verified"], result.get("local_zk_verified"))
+```
+
+## Commit data to the chain (STAMP)
+
+STAMP writes any JSON-serialisable record to the chain permanently. The result is unforgeable, publicly verifiable, and Bitcoin-anchored.
+
+```python
+client.faucet("my-wallet")                      # 100 free test MKV
+proof = client.stamp({"event": "audit-2026"}, wallet="my-wallet")
+print(proof["verify_url"])
+```
+
+## Tiers
+
+| Tier       | Access                                  | Key |
+|------------|-----------------------------------------|-----|
+| Free       | 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
+
+- `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
+- `verify(merkle_root, local)` — verify a proof against the registry, optionally re-running the ZK circuit locally
+- `stamp(data, wallet)` — commit a record to the chain
+- `faucet(wallet)` — claim test MKV
+- `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.

markovian-1.0.0/markovian.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+markovian.py
+pyproject.toml
+markovian.egg-info/PKG-INFO
+markovian.egg-info/SOURCES.txt
+markovian.egg-info/dependency_links.txt
+markovian.egg-info/entry_points.txt
+markovian.egg-info/requires.txt
+markovian.egg-info/top_level.txt

markovian-1.0.0/markovian.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

markovian-1.0.0/markovian.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+markovian = markovian:_cli

markovian-1.0.0/markovian.egg-info/requires.txt

@@ -0,0 +1,3 @@
+requests>=2.25
+numpy>=1.20
+py_ecc>=6.0

markovian-1.0.0/markovian.egg-info/top_level.txt

@@ -0,0 +1 @@
+markovian

markovian-1.0.0/markovian.py

@@ -0,0 +1,470 @@
+#!/usr/bin/env python3
+"""
+markovian.py - Markovian Protocol Python SDK
+Version 1.0 - June 2026
+
+Query regime data, verify ZK proofs, and subscribe to state changes
+from the Markovian Protocol Layer 1.
+
+Install:
+    pip install requests numpy py_ecc
+
+Usage:
+    from markovian import MarkovianClient
+
+    client = MarkovianClient()                        # free tier, no key
+    client = MarkovianClient(api_key="your-key")      # pro/enterprise
+
+    # Latest regime snapshot (liquid tickers)
+    snap = client.latest()
+
+    # Regime history for a ticker
+    df = client.regime("QQQ", days=90)
+
+    # Batch query
+    data = client.batch(["SPY", "QQQ", "GLD", "TLT"], days=30)
+
+    # Verify a ZK proof
+    result = client.verify(merkle_root)
+
+    # Chain tip
+    tip = client.tip()
+
+    # Block by height
+    block = client.block(18000)
+
+    # Watch for regime changes (polling)
+    client.watch(["QQQ", "SPY"], callback=my_fn, interval=60)
+"""
+
+import hashlib
+import time
+from typing import Callable, Dict, List, Optional
+
+import numpy as np
+import requests
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+__version__  = "1.0.0"
+BASE_URL     = "https://api.quantsynth.net"
+CHAIN_URL    = "https://api.quantsynth.net"
+
+STATES       = ["ACCUMULATION", "MARKUP", "DISTRIBUTION"]
+STATE_SHORT  = {"ACCUMULATION": "ACCUM", "MARKUP": "MUP", "DISTRIBUTION": "DIST"}
+
+GENESIS_M = np.array([
+    [0.70, 0.25, 0.05],
+    [0.10, 0.75, 0.15],
+    [0.20, 0.15, 0.65],
+], dtype=np.float64)
+
+
+# ── Regime object ─────────────────────────────────────────────────────────────
+
+class Regime:
+    """A single regime observation for a ticker on a date."""
+
+    def __init__(self, data: dict):
+        self._d       = data
+        self.ticker   = data.get("ticker", "")
+        self.date     = data.get("date") or data.get("obs_date", "")
+        self.regime   = data.get("regime", "")
+        self.confidence = float(data.get("confidence", 0))
+        raw = data.get("s_output") or data.get("s_input") or []
+        if isinstance(raw, str):
+            import json
+            raw = json.loads(raw)
+        self.p_accum    = float(raw[0]) if len(raw) > 0 else 0.0
+        self.p_markup   = float(raw[1]) if len(raw) > 1 else 0.0
+        self.p_dist     = float(raw[2]) if len(raw) > 2 else 0.0
+
+    def __repr__(self):
+        return f"Regime({self.ticker} {self.date}: {self.regime} {self.confidence*100:.1f}%)"
+
+    def to_dict(self):
+        return {
+            "ticker":     self.ticker,
+            "date":       self.date,
+            "regime":     self.regime,
+            "confidence": round(self.confidence, 4),
+            "p_accum":    round(self.p_accum, 4),
+            "p_markup":   round(self.p_markup, 4),
+            "p_dist":     round(self.p_dist, 4),
+        }
+
+    @property
+    def is_bullish(self):
+        return self.regime == "MARKUP"
+
+    @property
+    def is_bearish(self):
+        return self.regime == "DISTRIBUTION"
+
+    @property
+    def is_accumulating(self):
+        return self.regime == "ACCUMULATION"
+
+
+# ── Verify (standalone, no API needed) ───────────────────────────────────────
+
+def _verify_local(proof_dict: dict) -> dict:
+    """
+    Verify a MarkovProof locally using the BN128 ZK circuit.
+    No network call. Requires: pip install py_ecc numpy
+    Full spec: chain.quantsynth.net/zkspec
+    """
+    try:
+        from py_ecc.bn128 import G1, multiply, add, neg, curve_order
+        from py_ecc.fields import bn128_FQ as FQ
+
+        _H_SEED = int(hashlib.sha256(b"Markovian-H-generator-v1").hexdigest(), 16) % curve_order
+        H       = multiply(G1, _H_SEED)
+        M_DENOM = 20
+        TOLERANCE = 50
+
+        def _sm(k, P): k = int(k) % curve_order; return None if k == 0 else multiply(P, k)
+        def _pa(P, Q):
+            if P is None: return Q
+            if Q is None: return P
+            return add(P, Q)
+        def _ps(P, Q): return _pa(P, neg(Q))
+        def _ec(p): return (FQ(int(p[0])), FQ(int(p[1]))) if p else None
+        def _hash(*p): return int(hashlib.sha256(b"||".join(str(x).encode() for x in p)).hexdigest(), 16) % curve_order
+
+        M     = GENESIS_M
+        Mt    = M.T
+        M_INT = [[round(Mt[r, c] * M_DENOM) for c in range(3)] for r in range(3)]
+
+        n_steps = int(proof_dict["n_steps"])
+        steps   = proof_dict["steps"]
+        m_ver   = int(proof_dict["m_version"])
+        ctx_b   = f"mkv|v{m_ver}|N={n_steps}".encode()
+
+        if len(steps) != n_steps:
+            return {"verified": False, "error": f"step count mismatch: {len(steps)} != {n_steps}"}
+
+        for i, step in enumerate(steps):
+            for j in range(3):
+                eps = step["epsilons"][j]
+                if abs(eps) > TOLERANCE:
+                    return {"verified": False, "error": f"step {i} j={j} epsilon={eps} > tolerance"}
+                D = _sm(M_DENOM, _ec(step["C_out"][j]))
+                for k in range(3):
+                    D = _ps(D, _sm(M_INT[j][k], _ec(step["C_in"][k])))
+                if eps != 0:
+                    D = _ps(D, _sm(int(eps) % curve_order, H))
+                ctx = ctx_b + f"|i={i}|step|j={j}|eps={eps}".encode()
+                pf  = step["proofs"][j]
+                R   = _ec(pf["R"])
+                s, e = int(pf["s"]), int(pf["e"])
+                if _pa(_sm(s, G1), _sm(e, D)) != R:
+                    return {"verified": False, "error": f"Schnorr failed at step {i} j={j}"}
+                e2 = _hash([int(D[0]), int(D[1])], [int(R[0]), int(R[1])], ctx)
+                if e2 != e:
+                    return {"verified": False, "error": f"Fiat-Shamir mismatch step {i} j={j}"}
+            if i < n_steps - 1 and step["C_out"] != steps[i + 1]["C_in"]:
+                return {"verified": False, "error": f"chain break between step {i} and {i+1}"}
+
+        return {"verified": True, "n_steps": n_steps, "m_version": m_ver}
+    except ImportError:
+        return {"verified": None, "error": "py_ecc not installed: pip install py_ecc"}
+    except Exception as e:
+        return {"verified": False, "error": str(e)}
+
+
+# ── Client ────────────────────────────────────────────────────────────────────
+
+class MarkovianClient:
+    """
+    Markovian Protocol API client.
+
+    Free tier (no key): liquid tickers, 90-day window, 90 rows/call.
+    Pro/Enterprise:     all tickers, full history, CSV export.
+
+    Get a key: https://alphasynth.net
+    ZK spec:   https://chain.quantsynth.net/zkspec
+    """
+
+    def __init__(self, api_key: Optional[str] = None, timeout: int = 30):
+        self.api_key = api_key
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({
+            "User-Agent": f"markovian-sdk/{__version__}",
+            "Accept":     "application/json",
+        })
+        if api_key:
+            self._session.headers["X-API-Key"] = api_key
+
+    def _get(self, path: str, params: dict = None) -> dict:
+        r = self._session.get(f"{BASE_URL}{path}", params=params, timeout=self.timeout)
+        r.raise_for_status()
+        return r.json()
+
+    # ── Regime data ───────────────────────────────────────────────────────────
+
+    def latest(self) -> List[Regime]:
+        """Latest regime snapshot for major liquid tickers. Keyless / free tier."""
+        data = self._get("/data/latest")
+        regimes = data.get("regimes", {}) if isinstance(data, dict) else data
+        if isinstance(regimes, dict):
+            out = []
+            for ticker, v in regimes.items():
+                rec = dict(v)
+                rec.setdefault("ticker", ticker)
+                out.append(Regime(rec))
+            return out
+        return [Regime(v) for v in regimes]
+
+    def regime(self, ticker: str, days: int = 90, fmt: str = "json") -> List[Regime]:
+        """
+        Regime history for a single ticker.
+
+        Args:
+            ticker: e.g. "QQQ", "SPY", "GLD"
+            days:   lookback window in days (free tier max: 90)
+            fmt:    "json" or "csv" (pro/enterprise only)
+        """
+        import datetime as _dt
+        ticker = ticker.upper()
+        params = {"limit": days}
+        if days:
+            params["from"] = (_dt.date.today() - _dt.timedelta(days=days)).isoformat()
+        if fmt == "csv":
+            params["format"] = "csv"
+        try:
+            data = self._get(f"/data/regime/{ticker}", params)
+        except requests.HTTPError as e:
+            # No observations in the requested window is not an error: return empty.
+            if e.response is not None and e.response.status_code == 404:
+                return [] if fmt != "csv" else ""
+            raise
+        if fmt == "csv":
+            return data
+        rows = data if isinstance(data, list) else data.get("data", [])
+        return [Regime({**r, "ticker": r.get("ticker", ticker)}) for r in rows]
+
+    def batch(self, tickers: List[str], date: str = None) -> Dict[str, Regime]:
+        """
+        Latest (or as-of `date`) regime snapshot for multiple tickers.
+
+        Args:
+            tickers: list of tickers, e.g. ["SPY", "QQQ", "GLD"]
+            date:    optional "YYYY-MM-DD"; defaults to the most recent observation
+
+        Returns a dict keyed by ticker -> Regime.
+        """
+        params = {"tickers": ",".join(t.upper() for t in tickers)}
+        if date:
+            params["date"] = date
+        data = self._get("/data/batch", params)
+        rows = data.get("data", {}) if isinstance(data, dict) else {}
+        result = {}
+        for ticker, rec in rows.items():
+            if isinstance(rec, dict):
+                r = dict(rec)
+                r.setdefault("ticker", ticker)
+                result[ticker] = Regime(r)
+        return result
+
+    def catalog(self) -> dict:
+        """List available tickers and coverage dates."""
+        return self._get("/data/catalog")
+
+    # ── Chain ─────────────────────────────────────────────────────────────────
+
+    def tip(self) -> dict:
+        """Latest chain tip: height, hash, difficulty."""
+        return self._get("/tip")
+
+    def block(self, height: int) -> dict:
+        """Fetch a specific block by height."""
+        return self._get(f"/block/{height}")
+
+    def ledger(self) -> dict:
+        """MKV ledger summary: total blocks, MKV issued, Kovs issued."""
+        return self._get("/ledger/summary")
+
+    # ── Verification ──────────────────────────────────────────────────────────
+
+    def verify(self, merkle_root: str, local: bool = False) -> dict:
+        """
+        Verify a Merkle root against the provenance registry.
+
+        Args:
+            merkle_root: 64-char hex string
+            local:       if True, re-verify ZK proof locally (requires py_ecc)
+        """
+        result = self._get(f"/verify/{merkle_root}", {"format": "json"})
+        if local and result.get("zk_proof"):
+            local_check = _verify_local(result["zk_proof"])
+            result["local_zk_verified"] = local_check.get("verified")
+        return result
+
+    def verify_archive(self, root_hash: str) -> dict:
+        """Verify an archive Merkle root against on-chain commitments."""
+        return self._get(f"/archive/verify/{root_hash}")
+
+    # ── STAMP ─────────────────────────────────────────────────────────────────
+
+    def stamp(self, data, wallet: str, label: str = None) -> dict:
+        """
+        STAMP interface — commit any data to the chain permanently.
+
+        Burns 1 MKV from wallet. Returns merkle_root + ZK commitment.
+        The record is unforgeable, publicly verifiable, Bitcoin-anchored.
+
+        Args:
+            data:   any JSON-serialisable value (dict, list, string, number)
+            wallet: MKV wallet address (get test MKV via client.faucet())
+            label:  optional human-readable label for this stamp
+
+        Returns dict with: ok, stamp_id, merkle_root, zk_commitment,
+            block_height, stamped_at, mkv_burned, mkv_balance, verify_url
+
+        Example:
+            regime = client.latest()[0]
+            proof  = client.stamp(regime.to_dict(), wallet='my-wallet')
+            print(proof['verify_url'])
+        """
+        r = self._session.post(
+            f"{BASE_URL}/stamp",
+            json={"wallet": wallet, "data": data, "label": label},
+            timeout=self.timeout,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def stamps(self, wallet: str, limit: int = 20) -> list:
+        """List all STAMP records for a wallet."""
+        return self._get(f"/stamps/{wallet}", {"limit": limit})
+
+    # ── MKV ──────────────────────────────────────────────────────────────────
+
+    def faucet(self, wallet: str) -> dict:
+        """
+        Get 100 free test MKV. One grant per wallet, one per IP per 24h.
+        No API key required.
+
+        Args:
+            wallet: any string identifier for your wallet address
+
+        Returns dict with: ok, wallet, granted, balance, next
+
+        Example:
+            result = client.faucet('my-builder-wallet')
+            print(result['balance'])  # 100
+        """
+        r = self._session.post(
+            f"{BASE_URL}/mkv/faucet",
+            json={"wallet": wallet},
+            timeout=self.timeout,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def mkv_balance(self, wallet: str) -> int:
+        """Current MKV balance for a wallet."""
+        return self._get(f"/mkv/balance/{wallet}").get("balance_mkv", 0)
+
+    # ── Watch ─────────────────────────────────────────────────────────────────
+
+    def watch(
+        self,
+        tickers: List[str],
+        callback: Callable,
+        interval: int = 60,
+        max_iters: Optional[int] = None,
+    ):
+        """
+        Poll for regime changes and call callback on state transitions.
+
+        Args:
+            tickers:   list of tickers to monitor
+            callback:  fn(ticker, old_regime, new_regime, observation)
+            interval:  polling interval in seconds
+            max_iters: stop after N polls (None = run forever)
+
+        Example:
+            def on_change(ticker, old, new, obs):
+                print(f"{ticker}: {old} -> {new}")
+
+            client.watch(["QQQ", "SPY"], on_change)
+        """
+        tickers    = [t.upper() for t in tickers]
+        last_state = {}
+        iters = 0
+
+        print(f"Watching {tickers} every {interval}s. Ctrl+C to stop.")
+
+        while True:
+            try:
+                snapshot = self.batch(tickers)
+                for ticker, latest in snapshot.items():
+                    prev = last_state.get(ticker)
+                    if prev and prev.regime != latest.regime:
+                        callback(ticker, prev.regime, latest.regime, latest)
+                    last_state[ticker] = latest
+            except Exception as e:
+                print(f"  watch error: {e}")
+
+            iters += 1
+            if max_iters and iters >= max_iters:
+                break
+            time.sleep(interval)
+
+
+# ── CLI ───────────────────────────────────────────────────────────────────────
+
+def _cli():
+    import sys, json
+
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return
+
+    cmd    = sys.argv[1]
+    client = MarkovianClient()
+
+    if cmd == "latest":
+        regimes = client.latest()
+        for r in regimes:
+            print(f"  {r.ticker:<8} {r.regime:<14} {r.confidence*100:.1f}%  {r.date}")
+
+    elif cmd == "regime" and len(sys.argv) >= 3:
+        ticker = sys.argv[2]
+        days   = int(sys.argv[3]) if len(sys.argv) > 3 else 90
+        rows   = client.regime(ticker, days=days)
+        for r in rows[-20:]:
+            bar = "#" * int(r.confidence * 20)
+            print(f"  {r.date}  {r.regime:<14} {r.confidence*100:.1f}%  {bar}")
+
+    elif cmd == "tip":
+        tip = client.tip()
+        print(json.dumps(tip, indent=2))
+
+    elif cmd == "verify" and len(sys.argv) >= 3:
+        result = client.verify(sys.argv[2])
+        print(json.dumps(result, indent=2))
+
+    elif cmd == "ledger":
+        led = client.ledger()
+        print(json.dumps(led, indent=2))
+
+    elif cmd == "batch" and len(sys.argv) >= 3:
+        tickers = sys.argv[2].split(",")
+        data    = client.batch(tickers)
+        for ticker, rows in data.items():
+            if rows:
+                r = rows[-1] if isinstance(rows, list) else rows
+                if hasattr(r, 'regime'):
+                    print(f"  {ticker:<8} {r.regime:<14} {r.confidence*100:.1f}%  {r.date}")
+
+    else:
+        print(f"Unknown command: {cmd}")
+        print("Commands: latest, regime <TICKER> [days], tip, ledger, verify <root>, batch <T1,T2>")
+
+
+if __name__ == "__main__":
+    _cli()

markovian-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "markovian"
+version = "1.0.0"
+description = "Python SDK for the Markovian Protocol: verifiable market-regime data, on-chain ZK proofs, and STAMP commitment from a proof-of-intelligence Layer 1."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Markovian Protocol", email = "hello@quantsynth.net" }]
+keywords = [
+  "markovian", "oracle", "zk", "zero-knowledge", "blockchain",
+  "market-regime", "defi", "prediction-markets", "markov", "provenance",
+]
+dependencies = ["requests>=2.25", "numpy>=1.20", "py_ecc>=6.0"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Security :: Cryptography",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://markovianprotocol.com"
+Documentation = "https://markovianprotocol.com/build"
+Source = "https://github.com/MarkovianProtocol/markovian-protocol"
+Explorer = "https://chain.quantsynth.net"
+
+[project.scripts]
+markovian = "markovian:_cli"
+
+[tool.setuptools]
+py-modules = ["markovian"]

markovian-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+