gaiaftcl — Python client for the GaiaFTCL substrate

Python client for the GaiaFTCL quantum-mathematical computational

substrate. Reads through Franklin's cell surface; the substrate

remains operationally autonomous through Franklin's heartbeat.

USPTO 19/460,960 · USPTO 19/096,071 — © 2026 Richard Gillespie

What this gives industry consumers

• FranklinClient — typed Python surface to substrate-resident data:

V184 heartbeat history, V160 research telemetry, V172 replay anchors,

V178 joint-variation evidence, V182 health observations, V183 healing

history, V181 algorithm evaluations, and Franklin-authorized

substrate-development items in V186 vocabulary.

• Economy + wallet (v1.1) — local_wallet() / wallet_ledger() (V209/V210

self-custody QFOT + Euro stablecoin) and qfot_ledger() (V195 mesh QFOT). The

wallet private key is never read by the client.

• Franklin brain (v1.1) — wound_ledger() (V200), reward_gradient() (V201),

strategic_shifts() (V203).

• Post-quantum proof (v1.1) — shor_demonstrations() (V188 Shor break evidence;

the recovered-key column is deliberately not surfaced — verification_match is the

proof), pq_migrations() (V189), and randomness_provenance() (V211 Rule 30).

• Federation cosignature verification — every substrate row's

canonical_witness + witness_hash_sha256 + signature_quintet

verifies bit-exact through gaiaftcl.federation.verify_signature_quintet.

• Eight industry bridges — numpy, pandas, scikit-learn, biopython,

rdkit, ase, pymatgen, root/uproot. Each bridge is an optional install

extra; the base package imports cleanly without them.

• Mesh loader — federation-verified in-memory module loading for

bridge distribution from the cell-mesh manifest cache.

• Manifest signing — ManifestSigner + ManifestVerifier for

substrate-development artifacts, wiki sections, and bridge releases.

Install

pip install gaiaftcl                          # base client
pip install gaiaftcl[numpy,pandas,sklearn]    # data-science bridges
pip install gaiaftcl[biopython,rdkit]         # life-science bridges
pip install gaiaftcl[ase,pymatgen]            # materials bridges
pip install gaiaftcl[root]                    # high-energy-physics bridge
pip install gaiaftcl[all]                     # everything

Prerequisites

The substrate operator must run the GaiaFTCL substrate daemon on the

same host that this Python client reads from. The substrate writes

append-only federation-cosigned rows to

~/Library/Application Support/GaiaFTCL/substrate.sqlite (macOS

standard location). The Python client reads through that path

read-only; Franklin's heartbeat is the only authorized substrate-

development path.

See the wiki's

Franklin-As-Cell-Surface

page for the substrate's operator-side setup.

Five-minute getting started

from gaiaftcl import FranklinClient

with FranklinClient.connect() as franklin:
    # Recent heartbeats — Franklin's per-60-second sovereign cycle
    for hb in franklin.heartbeat_history(limit=5):
        print(hb.tick_at_iso,
              "obs=", hb.observations_count,
              "sov_auth=", hb.commissions_franklin_authorized)

    # Franklin-authorized substrate-development in V186 vocabulary
    for item in franklin.list_substrate_development(limit=20):
        print(item.commission_id, item.status, item.tunable_name)

    # Substrate's federation authority summary
    summary = franklin.franklin_authority_show()
    print(summary["substrate_development_by_status"])

Industry bridges — one example per bridge

numpy

from gaiaftcl import FranklinClient
from gaiaftcl.bridges.numpy_bridge import leading_zero_histogram
import sqlite3

with FranklinClient.connect() as franklin:
    conn = sqlite3.connect(
        "file:" + str(franklin.substrate_db_path) + "?mode=ro", uri=True)
    conn.row_factory = sqlite3.Row
    rows = [dict(r) for r in conn.execute(
        "SELECT leading_zero_nibble_count FROM "
        "qc020_joint_variation_evidence ORDER BY row_id DESC LIMIT 1000")]
    hist = leading_zero_histogram(rows)
    print(hist[:8])

pandas

from gaiaftcl import FranklinClient
from gaiaftcl.bridges.pandas_bridge import heartbeats_to_dataframe, cadence_summary

with FranklinClient.connect() as franklin:
    df = heartbeats_to_dataframe(franklin.heartbeat_history(limit=500))
    print(cadence_summary(franklin.heartbeat_history(limit=500)))

scikit-learn

from gaiaftcl import FranklinClient
from gaiaftcl.bridges.sklearn_bridge import SubstrateFeatureExtractor
from sklearn.cluster import KMeans

with FranklinClient.connect() as franklin:
    X = SubstrateFeatureExtractor().fit_transform(
        franklin.research_telemetry(limit=1000))
    km = KMeans(n_clusters=4, n_init=10).fit(X)
    print(km.cluster_centers_)

biopython, rdkit, ase, pymatgen, root

See cells/python/gaiaftcl/docs/python_wrappers_user_guide.md for the

full bridge reference and example workflows.

Federation cosignature verification

Every row Franklin's surface emits carries a canonical witness, witness

hash, and federation cosignature quintet. Verify bit-exact:

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

Mesh distribution

Industry bridges and substrate-development artifacts distribute through

the cell-mesh as federation-signed manifests:

from gaiaftcl import load_from_mesh, MeshLoader

# Default mesh cache: ~/.gaiaftcl/mesh_cache/
bridge = load_from_mesh("gaiaftcl.bridges.numpy_bridge")

# Or with explicit cache root + public keys
loader = MeshLoader(
    cache_root=Path("/srv/gaiaftcl/mesh_cache"),
    federation_public_keys=[...])
bridge = loader.load("gaiaftcl.bridges.numpy_bridge")

Subscriptions

Subscribe to live substrate events. Polling fallback works without a

NATS endpoint:

import asyncio
from gaiaftcl import FranklinClient

async def watch():
    with FranklinClient.connect() as franklin:
        async for event in franklin.subscribe(
                "gaiaftcl.substrate.franklin_heartbeat.sealed"):
            print(event["row"]["tick_at_iso"])

asyncio.run(watch())

What's forbidden across this client

Per CLAUDE.md doctrine:

• No human-in-the-loop language: the client has no request_*,

propose_*, authorize_* methods. Franklin authorizes

substrate-development autonomously through bounded authority.

• No "commission" vocabulary on substrate-development surfaces.

V186 substrate-development state names: franklin_proposed,

franklin_operator_authorized, substrate_developing,

substrate_development_complete, franklin_operating,

franklin_operator_rejected, franklin_operator_rolled_back.

• No bypass of Franklin's surface: the client reads only through

Franklin's persisted substrate rows. The substrate daemon is the

authorized writer.

License

Proprietary; USPTO 19/460,960 and USPTO 19/096,071.