GaiaFTCL Python Wrappers — Consumer Guide

For external operators integrating Python industry workflows with the GaiaFTCL

substrate through Franklin's surface. The wrappers distribute through the

GaiaFTCL mesh websites, not PyPI.

1. Import from the mesh (not pip)

You do not pip install gaiaftcl. You bootstrap the loader, then import wrappers

from federation-cosigned mesh URLs. The only thing your environment needs on

disk is the tiny mesh bootstrap (the gaiaftcl.mesh module), or you fetch it the

first time and register it in memory.

from gaiaftcl.mesh import load_from_mesh

# Each call fetches the source, verifies its federation cosignature quintet and
# witness hash against the mesh manifest, and registers it in memory.
load_from_mesh("https://gaiaftcl.com/python/gaiaftcl/franklin.py")
from gaiaftcl.franklin import Franklin

franklin = Franklin()
outcome = franklin.heartbeat_history(limit=10)   # verified V184 rows

If a source fails verification (witness hash mismatch or a malformed quintet),

load_from_mesh raises MeshDistributionError and nothing is imported.

For air-gapped development verification, each served file also carries an

embedded cosignature header; load_from_mesh(url, require_manifest=False)

accepts it when no manifest is reachable.

2. Read Franklin's sealed surface

Read verbs need no socket — they read the sealed, append-only, witness-bearing

substrate surface and verify each row:

f = Franklin()
for row in f.joint_variation_evidence(limit=100):   # V178
    assert row.verified and len(row.cosignatures) == 5
    print(row["leading_zero_nibble_count"], row["digest_hex"])

Typed wrappers:

from gaiaftcl import constitutional_invariants, JointVariationCursor, projections
inv = constitutional_invariants(f.constitutional_evaluations())   # C007-C010
cur = JointVariationCursor.from_rows(f.joint_variation_evidence(limit=500))
proj = projections(f.research_telemetry())

3. Command verbs require the operator-signed handshake

Substrate compositions route to Franklin's local socket and require an

operator-signed handshake. Provide your federation operator context and an

Ed25519 signature over the server challenge:

import os
os.environ["GAIAFTCL_OPERATOR_CONTEXT"]   = "operator:hel1-01"
os.environ["GAIAFTCL_OPERATOR_SIGNATURE"] = "<base64 Ed25519 signature>"

f = Franklin()
result = f.evaluate_all_algorithms()        # FranklinOutcome, federation-verified
print(result.witness_hash, result.cosignatures)

If the socket is not bound on the host, command verbs raise

FranklinSocketUnavailable. Anonymous connections are refused by the server.

4. Industry bridge usage

Bridges are read-only on the substrate side. They lazy-import their library, so

the package imports even where a library is absent; calling a bridge function

without its library raises a clear ImportError.

# numpy: V178 leading-zero distribution as an array (Phase-6 sample)
from gaiaftcl.industry import numpy_bridge
arr = numpy_bridge.leading_zero_distribution(f, limit=2442)   # shape == rows read

# pandas: the sealed research dataset as a DataFrame
from gaiaftcl.industry import pandas_bridge
df = pandas_bridge.research_dataset(f, limit=1000)

# scikit-learn: QC-001 period finder (command path; needs the operator socket)
from gaiaftcl.industry import sklearn_bridge
est = sklearn_bridge.GaiaFTCLPeriodFinder(f).fit(X)
y = est.predict(X)

# rdkit / ase / pymatgen / biopython: compose a substrate measurement on a structure
from gaiaftcl.industry import rdkit_bridge
outcome = rdkit_bridge.mol_to_measurement(f, mol)             # QC-007

Across the float boundary, exact-Rat substrate values become floats with

documented precision loss. Substrate-internal operations remain byte-exact;

your Python-side analysis operates on the substrate's externalized outputs and

never modifies substrate state.

5. Subscribe to substrate operations

import asyncio
async def watch():
    async for msg in f.subscribe("gaiaftcl.qc020.substrate.joint_variation_evidence.sealed"):
        print(msg["subject"], len(msg["data"]))
asyncio.run(watch())

6. What you can rely on

• Every outcome you receive is federation-verified before you see it.
• The substrate is never mutated from Python.
• The source-of-truth for the wrappers is the mesh website; you always run the

cosigned version the mesh serves.