mostlyright.finance.transcripts.capture.base

Capture-adapter ABC + the transient audio artifact.

The provider-aware webcast capture contract. Each adapter

``

detect“s the webcast URLs it handles and

``

capture“s an earnings event into an AudioArtifact: a transient temp file that is deleted after transcription. Captured audio is never stored or served; only transcript text and derived facts survive.

The ABC supports both post-call replay capture and an optional live-during-call stream. Providers without a fetchable live HLS endpoint raise LiveCaptureUnsupported and use the authoritative post-call path.

Classes

Class	Description
AudioArtifact(audio_path, ticker, call_id, …)	A captured-audio handle whose backing file is transient.
CaptureAdapter()	Provider-aware webcast capture contract.

Exceptions

Exception	Description
LiveCaptureUnsupported([message, …])	A capture adapter has no supported live-during-call endpoint.

class mostlyright.finance.transcripts.capture.base.AudioArtifact(audio_path, ticker, call_id, source_media_url, is_transient=True)

Bases: object

A captured-audio handle whose backing file is transient.

audio_path points at a temp file extracted from the captured webcast media. is_transient is True by design: the file must be deleted after transcription and is never persisted or served. cleanup() unlinks it; the artifact is also a context manager, so with adapter.capture(...) as a guarantees the audio is gone on exit even if transcription raises.

source_media_url / call_id / ticker carry the capture lineage for audit (which asset produced these bytes) without retaining the bytes.

• Parameters:
  • audio_path (str)
  • ticker (str)
  • call_id (str)
  • source_media_url (str)
  • is_transient (bool)

audio_path: str

call_id: str

cleanup()

Delete the transient audio file (idempotent — safe to call twice).

FileNotFoundError (an idempotent double-call, or an already-cleaned artifact) is suppressed silently. Any other OSError, such as PermissionError on a read-only mount, is suppressed but logged at error level: it must not propagate out of __exit__, which would mask the transcription error the with block was raising and that the caller must see. It still means copyrighted earnings audio survived on disk, so the log line names the path an operator must delete manually.

• Return type: None

is_transient: bool

source_media_url: str

ticker: str

class mostlyright.finance.transcripts.capture.base.CaptureAdapter

Bases: ABC

Provider-aware webcast capture contract.

Concrete adapters implement detect() (does this adapter handle the URL?) and capture() (event → transient AudioArtifact). Providers with a fetchable live stream can also override live().

abstractmethod capture(event, **kwargs)

Capture event to a transient AudioArtifact.

An implementation must stay on the public path (no auth, DRM, or captcha circumvention) and must return an artifact whose backing file is transient. Raise CaptureNotAvailableError when the provider template exposes no cold-fetchable HTTP media (for example a dial-in bridge) rather than emitting empty audio.

• Return type: AudioArtifact
• Parameters:
  • event (dict [str , Any ])
  • kwargs (Any)

abstractmethod detect(url)

Return True iff this adapter handles url’s webcast provider.

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

live(manifest_url, session=None)

Follow the provider’s live edge, yielding (pcm_frame, spoken_at).

Reserved live-during-call entry point. A concrete adapter with a fetchable live HLS endpoint overrides this to open a rolling-window live capturer against manifest_url and stream PCM frames into the streaming STT. Audio stays a transient frame stream: the generator yields decoded PCM to the consumer and never writes audio to disk or serves it.

The ABC default raises LiveCaptureUnsupported. A provider with no live endpoint (dial-in bridge, SABR/YouTube, replay-only such as Lumi) has no live path, and the runner routes it to the authoritative post-call batch ledger instead. session carries any header-gated context (Origin/Referer/User-Agent/token) a provider needs; Q4 over IVS needs none.

• Return type: Iterator[tuple[bytes, float]]
• Parameters:
  • manifest_url (str)
  • session (Any)

exception mostlyright.finance.transcripts.capture.base.LiveCaptureUnsupported(message=”, , error_code=None, source=None, request_id=None)

Bases: EarningsError

A capture adapter has no supported live-during-call endpoint.

Engine-local exception: it subclasses the core EarningsError so callers filter it with the rest of the earnings-pipeline errors, but it is deliberately not added to packages/core — the live capture path is engine-only and must never touch the parity-critical modules (research(), merge/*, _live/_sources.py). Raised by CaptureAdapter.live() (the ABC default) for providers whose template has no fetchable live HLS endpoint: a telephone dial-in bridge, an unverified SABR/YouTube stream, or a replay-only provider such as Lumi. The runner routes such a provider to the post-call batch path and never opens a live session.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

message: str

request_id: str | None

source: str | None