mostlyright.finance.transcripts

mostlyright.finance.transcripts — the earnings-call transcript pipeline.

This sub-namespace homes the full pipeline that used to be split across the weather and markets wheels:

Engine (capture → STT → fact/ledger → segment bus) : The on-device capture + STT engine for the transcripts.live source AND the exact code “our infra” runs centrally for the default transcripts.hosted path. Heavy runtime deps (faster-whisper for STT, av for the transient audio extract) live behind the [transcripts] optional extra and are LAZY-imported inside the capture/STT methods — so importing this module and running the unit tests needs only the base finance deps. Audio is a TRANSIENT artifact, deleted post-transcription; only transcript text and derived facts survive (the legal audio firewall).

Adapter + stream (adapter, _stream) : The thin EarningsAdapter consumer/parser and the SSE consume_sse reader.

Market resolution (resolver, registries, pit, polymarket_derive) : The prediction-market earnings-mention universe: resolve a Kalshi KXEARNINGSMENTION{TICKER} / Polymarket “will say ” series, the codegen source-of-truth registries + calendar seed, and the point-in-time helpers (knowledge_time = transcript availability — the leakage boundary).

Canonical schemas are the contract. The engine imports EarningsTranscriptSchema / EarningsFactSchema DIRECTLY from mostlyright.core.schemas and re-exports them here — the canonical schemas ARE the contract for both the local transcripts.live path and the hosted serving layer; there is no separate byte-equivalent mirror to keep in sync.

class mostlyright.finance.transcripts.EarningsFactSchema

Bases: Schema

schema.finance.fact.v1 — one row per counted mention occurrence.

Carries the six RESEARCH-MARKETS §2 taxonomy dimensions (term match rule, counting mode, speaker scope, window scope, time, tie-break/resolution) plus the role_source provenance and the derived kalshi_counted flag, so the SAME fact rows resolve correctly under each venue’s wording.

mention_count is the integer PRIMARY tally; the boolean (“said ≥ 1”) is derived as mention_count >= 1 — storing only a bool cannot settle Polymarket “say X 5+ times” threshold brackets (RESEARCH-MARKETS §2.1(2)).

columns: ClassVar[list[ColumnSpec]]

schema_id: ClassVar[str]

class mostlyright.finance.transcripts.EarningsResolution(ticker, target_word, event_date, resolution_rule, resolution_status=‘qualifying_event’)

Bases: object

The frozen tuple a Kalshi earnings-mention contract resolves to.

Mirrors NHighResolution: an immutable (ticker, target_word, event_date, resolution_rule) carrier so a resolution cannot be mutated downstream (the frozen-tuple contract the TS twin mirrors via Object.freeze).

• Parameters:
  • ticker (str)
  • target_word (str)
  • event_date (date)
  • resolution_rule (str)
  • resolution_status (str)

event_date: date

resolution_rule: str

resolution_status: str

Whether a qualifying call exists for this date. "qualifying_event" for a normal resolution; "no_qualifying_event" when the Polymarket derive sees a postponed/cancelled call (RESEARCH-MARKETS §2.1(6)). Defaulted so the Kalshi resolve path is unchanged.

target_word: str

ticker: str

class mostlyright.finance.transcripts.EarningsTranscriptSchema

Bases: Schema

schema.finance.transcript.v1 — one row per transcript segment.

columns: ClassVar[list[ColumnSpec]]

schema_id: ClassVar[str]

class mostlyright.finance.transcripts.EndOfCall(call_id)

Bases: object

End-of-call control sentinel: the streaming engine finished call_id.

Published by SegmentBus.close() and delivered LAST to every live subscriber so the SSE route can emit a terminating end_of_call frame and close the connection cleanly (no dangling generator / leaked subscriber). It is a TEXT/control marker only — carries no audio.

• Parameters: call_id (str)

call_id: str

class mostlyright.finance.transcripts.FactDelta(term_canonical, matched_surface_form, mention_count, speaker_role, role_source, speaker_name, kalshi_counted, is_final, spoken_at, stream_seq, compound_type=‘standalone’, resolution_status=‘provisional’, source=‘earnings_call’)

Bases: object

A provisional live fact delta counted off a FINAL segment (never a partial).

Shaped for schema.finance.fact.v1: resolution_status="provisional" (live early-signal — NOT a settlement source), is_final=True (STT finality — orthogonal to authority), kalshi_counted derived via the unchanged fail-closed validate_kalshi_counted_occurrence() (mode-agnostic). TEXT/facts only — no audio.

compound_type is the per-delta compound axis — one delta per (term, compound_type), never an aggregate mixing types, so the venue filters in fact_builder apply row-wise (closed candidates surface for Polymarket human review; Kalshi-No on closed). ADDITIVE with default "standalone": an existing SSE consumer or a persisted pre-fix delta is unaffected (standalone counts for both venues exactly as before the axis).

• Parameters:
  • term_canonical (str)
  • matched_surface_form (str)
  • mention_count (int)
  • speaker_role (str)
  • role_source (str)
  • speaker_name (str | None)
  • kalshi_counted (bool)
  • is_final (bool)
  • spoken_at (float)
  • stream_seq (int)
  • compound_type (str)
  • resolution_status (str)
  • source (str)

compound_type: str

is_final: bool

kalshi_counted: bool

matched_surface_form: str

mention_count: int

resolution_status: str

role_source: str

source: str

speaker_name: str | None

speaker_role: str

spoken_at: float

stream_seq: int

term_canonical: str

to_stt_count(, turn_index=None)

Map this delta to a build_fact_rows stt_counts occurrence record.

The propagation seam (review F1): compound_type survives from the live classifier through the occurrence record into the fact row, so the venue filters + the fail-loud closed-candidate resolution operate on the SAME axis end-to-end. turn_index (when known) links the occurrence to the role-parser turns list so build_fact_rows re-derives the speaker scope from the authoritative turn.

TEMPORAL MAPPING: this delta’s spoken_at is an ENGINE-RELATIVE float (seconds into the stream, e.g. 12.5), NOT a wallclock. It maps into offset_seconds — the schema’s engine-relative int audit field, which build_fact_rows already accepts. It is NEVER emitted as the occurrence’s spoken_at: that schema column is timestamp_utc and pyarrow silently coerces a float to microseconds-after-epoch, persisting 1970-01-01 00:00:00.000012+00:00 as the temporal audit marker. spoken_at is left ABSENT (the column is nullable); a caller holding a genuine tz-aware wallclock sets it on the occurrence record explicitly — build_fact_rows fail-louds on any non-tz-aware-datetime value.

• Return type: dict[str, object]
• Parameters: turn_index (int | None)

class mostlyright.finance.transcripts.FactLedger(root=None)

Bases: _ParquetLedger

Append-only schema.finance.fact.v1 counted-mention ledger (no audio).

• Parameters: root (Path | str | None)

class mostlyright.finance.transcripts.ResumeIncomplete(from_seq, earliest_retained_seq)

Bases: object

Resume marker: from_seq predates the ring buffer’s earliest retained seq.

Yielded FIRST to a resubscribing consumer whose requested from_seq is older than anything the bounded ring buffer still holds — the gap between from_seq and earliest_retained_seq cannot be replayed from the bus, so the consumer MUST reconcile from the authoritative post-call ledger This is an EXPLICIT signal, never a silent gap.

• Parameters:
  • from_seq (int)
  • earliest_retained_seq (int)

earliest_retained_seq: int

from_seq: int

class mostlyright.finance.transcripts.RoleParser(roster=None)

Bases: object

Attribute transcript turns to speaker roles from TEXT cues only.

Construct with the published participant roster ((name, firm) pairs or RosterEntry rows). attribute_turns walks a segmented transcript and assigns each turn a speaker_role + role_source, resolving mangled analyst surnames via fuzzy_match_surname() gated on the firm token. A turn with no structural cue and no roster hit is left role_source="diarization_advisory" — NEVER a Kalshi-countable source.

• Parameters: roster (list [tuple [str , str ] ] | list [RosterEntry ] | None)

attribute_turns(transcript, roster=None)

Attribute every turn in transcript to a role from TEXT cues.

transcript is either the raw transcript text (parsed for operator announcements + self-IDs + label lines) OR a list of pre-segmented turn dicts ({"speaker_name": ..., "label": ..., "text": ...}). roster overrides the instance roster for this call.

Each returned Turn carries speaker_role + role_source. Un-anchorable turns get role_source="diarization_advisory".

• Return type: list[Turn]
• Parameters:
  • transcript (str | list [dict [str , object ] ])
  • roster (list [tuple [str , str ] ] | list [RosterEntry ] | None)

class mostlyright.finance.transcripts.RosterEntry(name, firm, role=‘unknown’)

Bases: object

A published-participant roster row: canonical name, firm, and role.

role is one of the SPEAKER_ROLE_VALUES (e.g. sell_side_analyst for an analyst, company_executive for a named exec). The firm token is the fuzzy-match guard — a surname is only repaired against entries sharing the cleanly-transcribed firm.

• Parameters:
  • name (str)
  • firm (str)
  • role (str)

firm: str

name: str

role: str

class mostlyright.finance.transcripts.Segment(text, is_final, spoken_at, stream_seq, knowledge_time, fact_deltas=)

Bases: object

One streaming transcript segment — TEXT ONLY (never audio).

is_final is STT-segment finality ONLY (partial vs final text); it NEVER gates settlement authority. spoken_at is the aired/event-time wallclock of the window’s start; knowledge_time is the STT-finalization/ publish wallclock (>= spoken_at). fact_deltas is populated on FINAL segments ONLY.

• Parameters:
  • text (str)
  • is_final (bool)
  • spoken_at (float)
  • stream_seq (int)
  • knowledge_time (float)
  • fact_deltas (list [FactDelta ])

fact_deltas: list[FactDelta]

is_final: bool

knowledge_time: float

spoken_at: float

stream_seq: int

text: str

class mostlyright.finance.transcripts.SegmentBus(, subscriber_queue_maxsize=256, ring_buffer_size=128, subscriber_hard_maxsize=None)

Bases: object

In-process asyncio per-call pub/sub bus (v1; Redis is a reserved seam).

• Parameters:
  • subscriber_queue_maxsize (int) – Bounded per-subscriber queue depth (drop-oldest-partial on overflow).
  • ring_buffer_size (int) – Per-call ring buffer depth of the last K FINAL events (resume backfill).
  • subscriber_hard_maxsize (int | None)

async close(call_id)

Signal end-of-call: deliver an EndOfCall marker to subscribers.

Each live subscriber receives the marker LAST (after any queued items); the SSE route yields it as a terminating end_of_call frame then closes cleanly. Idempotent — closing a call with no subscribers is a no-op.

• Return type: None
• Parameters: call_id (str)

is_closed(call_id)

Whether call_id has emitted end-of-call (a finished call).

• Return type: bool
• Parameters: call_id (str)

async publish(call_id, item)

Publish item to call_id — fan-out + ring-buffer the finals.

Rejects audio bytes / non-Segment-or-FactDelta objects. Appends FINAL items (final Segment or any FactDelta) to the per-call ring buffer. Puts to every subscriber queue with drop-oldest-partial backpressure; the publisher never blocks.

• Return type: None
• Parameters:
  • call_id (str)
  • item (object)

subscribe(call_id, from_seq=None)

Subscribe to call_id; return an async generator of items.

When from_seq is given, first replays ring-buffer FINALs with stream_seq > from_seq (gap recovery). If from_seq predates the ring buffer’s earliest retained seq, yields a ResumeIncomplete marker FIRST (reconcile from the ledger — never a silent gap). When from_seq is None, backfills the bounded ring buffer of recent finals. Then drains the live queue.

• Return type: AsyncIterator[Segment | FactDelta | ResumeIncomplete | EndOfCall]
• Parameters:
  • call_id (str)
  • from_seq (int | None)

subscriber_count(call_id)

Number of live subscribers on call_id (0 after clean teardown).

• Return type: int
• Parameters: call_id (str)

class mostlyright.finance.transcripts.SegmentBusProtocol(*args, **kwargs)

Bases: Protocol

The publish/subscribe contract the in-process bus satisfies.

A future cross-process (Redis/Memorystore) backplane would implement this same interface, so a multi-node deployment can fan segments across processes without changing the streaming engine or the SSE endpoint.

async publish(call_id, item)

• Return type: None
• Parameters:
  • call_id (str)
  • item (object)

subscribe(call_id, from_seq=None)

• Return type: AsyncIterator[Segment | FactDelta | ResumeIncomplete | EndOfCall]
• Parameters:
  • call_id (str)
  • from_seq (int | None)

class mostlyright.finance.transcripts.StreamingTranscriber(, transcriber=None, initial_prompt_terms=None, market_terms=None, turn_provider=None, model_size=‘small’)

Bases: object

VAD-chunked streaming STT → partial/final segments + final-only fact deltas.

• Parameters:
  • transcriber (Callable[..., str] | None) – A callable (window_pcm, *, initial_prompt) -> text. Injected so unit tests stub faster-whisper. When None, a lazy faster-whisper transcriber is built (DEFERRED / operator-only path).
  • initial_prompt_terms (Sequence[str] | None) – The market strike terms the per-call initial_prompt is seeded from (reuses seed_initial_prompt()).
  • market_terms (Sequence[Mapping[str, object]] | None) – Per-term market specs (term_canonical at minimum) the final-only counter runs over. When empty, no fact deltas are produced.
  • turn_provider (Callable[[Segment], Turn | None] | None) – Maps a segment to the role-parser Turn (speaker_role / role_source) driving the fail-closed Kalshi rule. Defaults to an unknown / diarization_advisory turn (Kalshi-excluded — fail-closed).
  • model_size (str)

fact_deltas: list[FactDelta]

All fact deltas emitted this run (final-only) — inspectable by callers.

run(frame_iter)

Consume (pcm_frame, spoken_at) frames → yield partial/final Segments.

For each VAD speech run: yields ONE revisable partial per accumulated window (is_final=False), then ONE final (is_final=True) on the speech-end boundary. The FINAL carries the STABILISED text of the ENTIRE run (every window’s transcription, overlap de-duplicated), NOT just the post-flush tail — so a term spoken early in a continuous run is counted exactly once. Fact deltas are computed on the FINAL segment only and appended to fact_deltas (and to the final segment’s fact_deltas list).

• Return type: Iterator[Segment]
• Parameters: frame_iter (Iterable [tuple [bytes , float ] ])

class mostlyright.finance.transcripts.TranscriptLedger(root=None)

Bases: _ParquetLedger

Append-only schema.finance.transcript.v1 segment ledger (no audio).

• Parameters: root (Path | str | None)

class mostlyright.finance.transcripts.Turn(speaker_name, speaker_role, role_source, firm=None, text=”, confidence=1.0)

Bases: object

A single attributed transcript turn.

speaker_role is a SPEAKER_ROLE_VALUES member; role_source is a ROLE_SOURCE_VALUES member. An un-anchorable turn carries role_source="diarization_advisory" (or "unknown") — never a Kalshi-countable source, so the downstream fail-closed filter excludes it from the Kalshi count.

• Parameters:
  • speaker_name (str | None)
  • speaker_role (str)
  • role_source (str)
  • firm (str | None)
  • text (str)
  • confidence (float)

confidence: float

firm: str | None

role_source: str

speaker_name: str | None

speaker_role: str

text: str

mostlyright.finance.transcripts.apply_kalshi_filter(rows)

Set kalshi_counted on every row via the fail-closed rule.

kalshi_counted = validate_kalshi_counted_occurrence(role_source, speaker_role) — True iff BOTH the role_source and speaker_role are Kalshi-anchorable. Un-anchorable occurrences (analyst Q&A, diarization_advisory role_source, unknown speaker) get False but are RETAINED in the returned rows for the Polymarket any-speaker count.

Returns NEW row dicts (does not mutate the inputs).

• Return type: list[dict[str, object]]
• Parameters: rows (Sequence *[*Mapping [str , object ] ])

mostlyright.finance.transcripts.build_fact_rows(stt_counts, turns, market_terms, , ticker, call_id, event_time=None)

Build schema.finance.fact.v1 rows — one per (ticker, call_id, term, occurrence).

stt_counts is a sequence of per-term occurrence records from the STT counter, each carrying at minimum term (the canonical market term), matched_surface_form (the actually-spoken string), and a turn_index linking the occurrence to the turns list (so its speaker role is known). Optional per-occurrence keys: offset_seconds, segment, confidence.

turns are role-parser Turn records (index-aligned with the transcript). market_terms is the per-term market spec carrying counting_mode, threshold_n, window_scope, term_match_rule, term_accepted_forms (JSON string), term_canonical — used to populate the venue-rule fields on each row.

Returns the rows with kalshi_counted ALREADY derived via apply_kalshi_filter() (fail-closed). Every occurrence is retained for the Polymarket any-speaker count; only kalshi_counted distinguishes the Kalshi-countable subset.

• Return type: list[dict[str, object]]
• Parameters:
  • stt_counts (Sequence [Mapping [str , object ] ])
  • turns (Sequence [Turn ])
  • market_terms (Sequence [Mapping [str , object ] ])
  • ticker (str)
  • call_id (str)
  • event_time (object)

mostlyright.finance.transcripts.derive(event)

Derive a frozen EarningsResolution from a Polymarket event payload.

The payload is untrusted. The derive refuses (returns None) when:

• the slug/title does not look like an earnings-mention market;
• the ticker is missing or not in EARNINGS_SERIES_ROSTER;
• a webcast_url is present but its host is NOT on WEBCAST_HOST_ALLOWLIST (security boundary — refuse before derive);
• target_word or event_date is missing / unparseable.

A postponed / cancelled call yields a resolution with resolution_status="no_qualifying_event" (RESEARCH-MARKETS §2.1(6)).

• Return type: EarningsResolution | None
• Parameters: event (dict [str , Any ])

mostlyright.finance.transcripts.detect_provider(webcast_url)

Name the webcast provider for webcast_url, or None.

The host is first checked against WEBCAST_HOST_ALLOWLIST (the security boundary): a non-allowlisted host returns None — it is NEVER fingerprinted from a raw substring (so a hostile evil.example/q4inc cannot spoof a provider). An allowlisted host is then matched against WEBCAST_PROVIDER_FINGERPRINTS by host substring.

• Return type: str | None
• Returns: The canonical provider id ("q4" etc.), or None when the host is non-allowlisted or matches no fingerprint.
• Parameters: webcast_url (str)

mostlyright.finance.transcripts.fuzzy_match_surname(spoken, roster, firm_token, , cutoff=0.72)

Repair a mangled analyst surname against the published roster.

spoken is the (possibly mis-transcribed) surname as heard — "DeFucci" for "DiFucci", "Elnick" for "Zelnick". roster is the published participant list as (name, firm) pairs (or RosterEntry rows). firm_token is the cleanly-transcribed firm — the fuzzy match is GATED on it: only roster entries whose firm matches firm_token (exact, normalized) are candidates, so a close surname in the WRONG firm can never be adopted (the cross-firm mis-attribution hazard).

Returns the roster’s CANONICAL surname on a confident match, else None. Uses difflib.get_close_matches() (stdlib): the surname-repair job is tiny, and difflib’s SequenceMatcher ratio comfortably resolves the 1-char / phonetic drifts observed (DeFucci→DiFucci ratio ~0.86, Elnick→Zelnick ~0.77). No third-party fuzzy dependency is pulled (no new-dep legitimacy gate).

• Return type: str | None
• Parameters:
  • spoken (str)
  • roster (list [tuple [str , str ] ] | list [RosterEntry ])
  • firm_token (str)
  • cutoff (float)

mostlyright.finance.transcripts.parse_operator_announcements(text)

Extract operator analyst hand-off announcements from text.

Returns one dict per announcement:

{"name": "John DiFucci", "firm": "Guggenheim",
 "role_source": "transcript_structural"}

The operator names every analyst by name+firm; this is the most reliable transcript-anchored role cue (§1). The extracted analyst is a sell_side_analyst — the caller assigns the role. Firm is captured verbatim so it can gate a downstream roster fuzzy-match on a mangled surname.

• Return type: list[dict[str, str]]
• Parameters: text (str)

mostlyright.finance.transcripts.resolve(contract_id, event_date, , target_word)

Resolve a Kalshi earnings-mention contract to its frozen tuple.

The contract_id is the Kalshi market identifier — one of the three root variants KXEARNINGSMENTION<TICKER> (e.g. KXEARNINGSMENTIONNKE), KXMENTIONEARN<TICKER>, or the Berkshire fixed root KXBRKEM. The suffix is the ticker; it is validated against EARNINGS_SERIES_ROSTER.

• Parameters:
  • contract_id (str) – Kalshi market identifier. Case-insensitive.
  • event_date (date) – The calendar date the call airs / the market settles for. Must be a datetime.date with NO time component.
  • target_word (str) – The word/phrase the market resolves on. Required, non-empty.
• Return type: EarningsResolution
• Returns: A frozen EarningsResolution.
• Raises:
  • TypeError – contract_id is not a string, event_date is a datetime (or any non-date), or target_word is not a string.
  • ValueError – contract_id matches no known root, the ticker suffix is empty, the ticker is not in EARNINGS_SERIES_ROSTER, or target_word is empty.

Modules

adapter	Earnings catalog adapter.
capture	Earnings webcast capture fleet.
catalog	Earnings discovery-time membership registries.
fact_builder	Earnings fact-row builder + fail-closed Kalshi filter.
ledger	Append-only transcript + fact parquet ledger.
pit	Point-in-time alignment + leakage wiring for earnings facts.
polymarket_derive	Polymarket earnings-mention derive + webcast provider fingerprint.
registries	Earnings codegen registries — source-of-truth dicts.
resolver	Kalshi earnings-mention resolver.
role_parser	Transcript-anchored role-attribution parser.
segment_bus	In-process asyncio segment/fact pub-sub bus.
streaming_transcriber	Streaming STT engine.
stt	faster-whisper STT transcriber + alias-aware mention counter.