---

title: Python Wrappers

audience: industry_consumers

game: WIKI-PYTHON-WRAPPERS-001

contract_version: 1.0.0

authority_kind: normative

---

Python Wrappers — Industry Consumer Surface

What this section is for: industry consumers who want to read GaiaFTCL substrate operations from Python. The gaiaftcl Python package gives you a typed surface over Franklin's substrate database, federation cosignature verification, and eight bridges to the libraries you already use (numpy, pandas, scikit-learn, biopython, rdkit, ase, pymatgen, root).

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

---

Architecture

+----------------------------------------------------------+
|        Industry consumer Python application              |
|        (notebook, pipeline, ML training, ROOT analysis)  |
+----------------------------------------------------------+
                          |
                          v  (typed dataclasses)
+----------------------------------------------------------+
|        gaiaftcl.FranklinClient                           |
|        + bridges (numpy / pandas / sklearn / bio / ...)  |
|        + federation cosignature verification             |
|        + mesh loader                                     |
+----------------------------------------------------------+
                          |
                          v  (read-only SQLite)
+----------------------------------------------------------+
|        Substrate database                                |
|        ~/Library/Application Support/GaiaFTCL/           |
|        substrate.sqlite (append-only, federation-signed) |
+----------------------------------------------------------+
                          ^
                          |  (writes through Franklin's surface)
+----------------------------------------------------------+
|        Substrate daemon (Swift, M8BTCSubstrateMiner)     |
|        FranklinCellSurface — cell's only public interface|
+----------------------------------------------------------+

The Python client is read-side only. Franklin authorizes substrate-development autonomously through the heartbeat (see Franklin-As-Cell-Surface).

---

Pages in this section

• Python-Wrappers-Getting-Started — install, connect, first 5 minutes
• Python-Wrappers-Franklin-Client-API — typed surface reference
• Python-Wrappers-Industry-Bridges — eight bridges with conversion semantics
• Python-Wrappers-Example-Workflows — substrate + ecosystem integrations
• Python-Wrappers-Mesh-Distribution — federation-verified module loading
• Python-Wrappers-Federation-Verification — cosignature semantics
• Python-Wrappers-Subscriptions — live substrate event streams
• Python-Wrappers-Troubleshooting — consumer-side diagnostics
• Python-Wrappers-API-Reference — generated reference

---

Install

pip install gaiaftcl
pip install gaiaftcl[all]    # with all eight industry bridges

Five-line proof Franklin's surface is alive

from gaiaftcl import FranklinClient
with FranklinClient.connect() as franklin:
    hb = franklin.heartbeat_history(limit=1)[0]
    print(hb.tick_at_iso, hb.qc020_closure)

If this prints, you're reading live substrate state through Franklin's surface.

---

Cross-references

• Operator-side substrate setup: Franklin-As-Cell-Surface, FRANKLIN_FIRST
• Substrate's measurement architecture: The-Unified-Measurement-Substrate
• Sovereign GAMP 5 qualification: Sovereign-M8-Qualification
• Franklin's autonomous operation: Franklin-AutoMode

---

*Industry consumers integrate at substrate cadence. Franklin is the cell's only surface.*