---

title: Python Wrappers — Franklin Client API

audience: industry_consumers

game: WIKI-PYTHON-WRAPPERS-FRANKLIN-CLIENT-API-001

---

Franklin Client API

gaiaftcl.FranklinClient is the typed Python surface over Franklin's substrate-resident state. Read-side only; Franklin's heartbeat is the authorized substrate-development path.

---

Connection

FranklinClient.connect(substrate_db_path: Path | None = None) -> FranklinClient

Open a read connection. Default substrate path is ~/Library/Application Support/GaiaFTCL/substrate.sqlite. Raises FranklinClientError if the database is absent.

Use as context manager:

with FranklinClient.connect() as franklin:
    ...
# connection closed on exit

---

heartbeat_history(limit=10) -> list[FranklinHeartbeat]

Recent V184 heartbeat rows from Franklin's 60-second sovereign cycle.

FranklinHeartbeat carries:

• heartbeat_id, tick_at_iso, daemon_session_id, tick_cadence_seconds
• observations_count, classifications_count, commission_proposals_count
• tuning_adjustments_applied, tuning_adjustments_held
• filtering_decisions_applied, game_evaluations_run
• healing_escalations_processed, invariant_set_evolution_actions
• commissions_franklin_authorized, commissions_implemented_by_substrate_developer,

commissions_activated, commissions_rolled_back

• substrate_state_summary_json — parse via .qc020_closure property
• canonical_witness, witness_hash_sha256, signature_quintet, nats_subject_sealed

---

research_telemetry(limit=100) -> list[dict]

V160 substrate research telemetry — one row per substrate measurement. Returned as dict to preserve the schema's full column set (variable across schema versions).

---

health_observations(limit=20) -> list[FranklinHealthObservation]

V182 substrate health observations. Carries the 8 per-cycle health flags (measurement composition, invariant preservation, anchor accumulation, algorithm evaluation, federation cosignature, NATS broadcast, resource consumption, Bitcoin RPC).

---

healing_history(limit=50) -> list[FranklinHealingAction]

V183 substrate healing actions. authority_path is substrate_autonomous (within bounds) or franklin_sovereign_authorization (Franklin authorizes through sovereign cycle). outcome in V186 vocabulary: success / failed_retrying / failed_escalated / franklin_operator_authorized / franklin_operator_rejected.

---

list_substrate_development(status=None, limit=100) -> list[FranklinSubstrateDevelopment]

Franklin-authorized substrate-development items.

Filter by status (V186 vocabulary):

• franklin_proposed
• franklin_operator_authorized
• substrate_developing
• substrate_development_complete
• franklin_operating
• franklin_operator_rejected
• franklin_operator_rolled_back

---

evaluate_algorithm(algorithm_id=None, limit=30) -> list[FranklinAlgorithmEvaluation]

V181 QC algorithm evaluation history. Filter by algorithm_id (e.g. qc-001 through qc-021).

---

replay_session(limit=100) -> list[FranklinReplayAnchor]

V172 substrate session replay anchors. Each anchor chains to its predecessor via prior_anchor_id. Replay verification recomputes each anchor's witness_hash_sha256 from the stored canonical_witness.

---

franklin_authority_show() -> dict

Summary of Franklin's sovereign authority state composed from the latest heartbeat + substrate-development status distribution.

Returns:

{
    "latest_heartbeat": { ... },
    "substrate_development_by_status": {
        "franklin_operating": 5,
        "franklin_operator_rejected": 3,
        ...
    }
}

---

async subscribe(subject: str) -> AsyncIterator[dict]

Subscribe to live substrate events. Default polling fallback yields newly-appended rows at 1-second cadence; NATS-bus path activates when ~/.gaiaftcl/nats.toml or GAIAFTCL_NATS_URL is configured.

Supported subjects:

• gaiaftcl.substrate.franklin_heartbeat.sealed — V184 heartbeats
• gaiaftcl.qc020.franklin.window_filtering.sealed — V170 filter writes
• gaiaftcl.qc020.substrate.joint_variation_evidence.sealed — V178 measurements
• gaiaftcl.substrate.healing_action.sealed — V183 healing actions

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"], event["row"]["observations_count"])

asyncio.run(watch())

---

Errors

• FranklinClientError — connection or read failure
• FranklinAuthorityViolation — raised if a Python-side operation attempts to bypass Franklin's bounded authority

---

*Franklin authorizes substrate-development autonomously. The client surfaces what the substrate has done.*