Skip to content

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):

Status Meaning
franklin_proposed Substrate observed a load-bearing gap; Franklin proposed substrate-development
franklin_operator_authorized Franklin's authorizer cleared the proposal against bounded authority
substrate_developing Substrate developer is implementing the authorized work
substrate_development_complete Implementation landed; awaits Franklin activation
franklin_operating Substrate-development active and operating
franklin_operator_rejected Refused-set action — Franklin rejected per franklin_sovereign_authority_bounds.toml
franklin_operator_rolled_back Post-change metric breached threshold; Franklin rolled back autonomously

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

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 475d4f7e7582ab6c…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.