---

title: Python Wrappers — Getting Started

audience: industry_consumers

game: WIKI-PYTHON-WRAPPERS-GETTING-STARTED-001

---

Python Wrappers — Getting Started

Install gaiaftcl, connect to the running substrate, read your first Franklin heartbeat.

---

Prerequisites

1. Substrate operator must be running the GaiaFTCL daemon. The Python client reads through the substrate's append-only federation-cosigned SQLite database at ~/Library/Application Support/GaiaFTCL/substrate.sqlite. If no daemon is running, the database may not exist or won't be accumulating rows. See FRANKLIN_FIRST for operator-side installation.

2. Python 3.10+.

3. Substrate operator has not blocked the read socket. The Python client uses SQLite read-only mode; no operator handshake is required for read access.

---

Install

Base client only:

pip install gaiaftcl

With selected industry bridges:

pip install gaiaftcl[numpy,pandas]
pip install gaiaftcl[sklearn]
pip install gaiaftcl[biopython,rdkit]
pip install gaiaftcl[ase,pymatgen]
pip install gaiaftcl[root]

Everything:

pip install gaiaftcl[all]

---

First connection

from gaiaftcl import FranklinClient

with FranklinClient.connect() as franklin:
    hb = franklin.heartbeat_history(limit=1)
    if not hb:
        print("No heartbeats yet — substrate just started?")
    else:
        h = hb[0]
        print(f"Latest tick: {h.tick_at_iso}")
        print(f"Observations: {h.observations_count}")
        print(f"QC-020 closure: {h.qc020_closure}")

Expected output (when daemon is running at 60-second cadence):

Latest tick: 2026-06-01T16:27:30Z
Observations: 654
QC-020 closure: {'check_1_v160_accumulating': 1, 'v160_recent_count': 654, ...}

---

Reading Franklin-authorized substrate-development

The substrate's sovereign cycle authorizes its own substrate-development items autonomously. The Python client surfaces the state machine in V186 vocabulary:

from gaiaftcl import FranklinClient
from collections import Counter

with FranklinClient.connect() as franklin:
    items = franklin.list_substrate_development(limit=50)
    counts = Counter(i.status for i in items)
    for status, n in sorted(counts.items()):
        print(f"  {status}: {n}")

Statuses you'll see (V186 vocabulary):

---

Federation cosignature verification

Every row Franklin surfaces carries canonical_witness + witness_hash_sha256 + signature_quintet. Verify:

from gaiaftcl import FranklinClient
from gaiaftcl.federation.cosignature import verify_signature_quintet

with FranklinClient.connect() as franklin:
    hb = franklin.heartbeat_history(limit=1)[0]
    ok = verify_signature_quintet(
        canonical_witness=hb.canonical_witness,
        witness_hash_sha256=hb.witness_hash_sha256,
        signature_quintet_json=hb.signature_quintet,
    )
    assert ok, "Federation verification failed — substrate divergence?"
    print(f"Heartbeat {hb.heartbeat_id} federation-verified ✓")

True means the witness hash is bit-exact equivalent to SHA-256(canonical_witness). With federation public keys passed in, full quintet signature verification fires per context.

---

CLI

The package ships a CLI:

gaiaftcl-py heartbeat --limit 5
gaiaftcl-py development --status franklin_operating
gaiaftcl-py health --limit 10
gaiaftcl-py healing
gaiaftcl-py authority
gaiaftcl-py replay --limit 5
gaiaftcl-py verify   # verifies the latest heartbeat federation cosignature

All commands write JSON to stdout for piping.

---

Next steps

• Python-Wrappers-Franklin-Client-API — full method reference
• Python-Wrappers-Industry-Bridges — eight bridges
• Python-Wrappers-Example-Workflows — substrate + ecosystem integrations