Skip to content

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.

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 505d97504515ffdd…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.