---

title: Python Wrappers — Example Workflows

audience: industry_consumers

game: WIKI-PYTHON-WRAPPERS-EXAMPLE-WORKFLOWS-001

---

Example Workflows

Substrate + ecosystem integrations. Each workflow reads through Franklin's surface, converts through an industry bridge, and verifies federation cosignature.

---

numpy — substrate cadence sliding window

import numpy as np
from gaiaftcl import FranklinClient
from gaiaftcl.bridges.numpy_bridge import heartbeat_counters_to_array

with FranklinClient.connect() as franklin:
    hbs = franklin.heartbeat_history(limit=200)
    obs = heartbeat_counters_to_array(hbs, "observations_count")
    print(f"window mean: {obs.mean():.2f}")
    print(f"deltas: {np.diff(obs)}")

---

pandas — substrate timeline + cadence health

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

with FranklinClient.connect() as franklin:
    hbs = franklin.heartbeat_history(limit=1000)
    df = heartbeats_to_dataframe(hbs)
    df["tick_at"] = pd.to_datetime(df["tick_at_iso"])
    df.set_index("tick_at")[
        ["observations_count", "filtering_decisions_applied"]
    ].plot(figsize=(10, 4))

    print(cadence_summary(hbs))

---

scikit-learn — cluster substrate measurement windows

from gaiaftcl import FranklinClient
from gaiaftcl.bridges.sklearn_bridge import SubstrateFeatureExtractor
from sklearn.preprocessing import StandardScaler
from sklearn.cluster import KMeans
from sklearn.pipeline import Pipeline

with FranklinClient.connect() as franklin:
    rows = franklin.research_telemetry(limit=2000)
    pipe = Pipeline([
        ("extract", SubstrateFeatureExtractor(
            fields=["substrate_iteration_count", "tick_within_window"])),
        ("scale", StandardScaler()),
        ("cluster", KMeans(n_clusters=4, n_init=10)),
    ])
    pipe.fit(rows)
    print("cluster centers:", pipe["cluster"].cluster_centers_)

---

biopython — substrate pathway projection corpus

from gaiaftcl import FranklinClient
from gaiaftcl.bridges.biopython_bridge import telemetry_to_seqrecords
from Bio import SeqIO

with FranklinClient.connect() as franklin:
    rows = franklin.research_telemetry(limit=500)
    records = telemetry_to_seqrecords(rows, alphabet="ACGT")
    with open("substrate_pathways.fasta", "w") as f:
        SeqIO.write(records, f, "fasta")

---

rdkit — Validated Cures corpus + substrate identity

from gaiaftcl.bridges.rdkit_bridge import (
    project_validated_cure_row, mol_to_substrate_projection_canonical
)
# Validated Cures corpus loaded via scripts/load_validated_cures.py;
# query the loaded SQLite for canonical SMILES.

cure_rows = [...]   # from validated_cures table
for row in cure_rows[:10]:
    mol = project_validated_cure_row(row)
    if mol is None:
        continue
    print(row["name"], "→", mol_to_substrate_projection_canonical(mol))

---

ase — substrate lattice → ASE workflow

from gaiaftcl.bridges.ase_bridge import lattice_canonical_to_atoms
from ase.calculators.emt import EMT

canonical = "symbols=['Cu','Cu'];positions=[[0,0,0],[1.8,1.8,1.8]];cell=[3.6,3.6,3.6]"
atoms = lattice_canonical_to_atoms(canonical)
atoms.calc = EMT()
print(f"potential energy: {atoms.get_potential_energy():.4f} eV")

---

pymatgen — substrate structure → phase diagram

from gaiaftcl.bridges.pymatgen_bridge import (
    structure_canonical_to_structure
)
from pymatgen.analysis.phase_diagram import PhaseDiagram

s = structure_canonical_to_structure("Fe2O3 (R-3c)", lattice_a=5.03)
print(s.composition.reduced_formula)
print(s.lattice.parameters)

---

root / uproot — substrate research telemetry → ROOT file

import uproot
from gaiaftcl import FranklinClient
from gaiaftcl.bridges.root_bridge import telemetry_to_uproot_tree

with FranklinClient.connect() as franklin:
    rows = franklin.research_telemetry(limit=50000)
    with uproot.recreate("substrate_telemetry.root") as f:
        f["telemetry"] = telemetry_to_uproot_tree(rows)

Read back in another tool:

import uproot
tree = uproot.open("substrate_telemetry.root")["telemetry"]
print(tree.keys())
arrays = tree.arrays(library="np")

---

Composing — federation-verify then bridge to pandas

from gaiaftcl import FranklinClient
from gaiaftcl.federation.cosignature import verify_signature_quintet
from gaiaftcl.bridges.pandas_bridge import heartbeats_to_dataframe

with FranklinClient.connect() as franklin:
    hbs = franklin.heartbeat_history(limit=1000)
    verified = [hb for hb in hbs
                if verify_signature_quintet(
                    hb.canonical_witness,
                    hb.witness_hash_sha256,
                    hb.signature_quintet)]
    df = heartbeats_to_dataframe(verified)
    print(f"verified: {len(verified)} / {len(hbs)}")

---

*Bridges compose freely. Federation verification + ecosystem analysis are orthogonal layers in your Python pipeline.*