live-earnings 0.4.0__tar.gz

live_earnings-0.4.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: live-earnings
+Version: 0.4.0
+Summary: Live Earnings — live, attributed earnings-call transcripts.
+Author: Live Earnings
+License: Proprietary
+Project-URL: Homepage, https://live-earnings.com/live/docs
+Project-URL: Documentation, https://live-earnings.com/live/docs
+Project-URL: Source, https://live-earnings.com/live/docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+
+# live-earnings
+
+Python client for the Live Earnings API: live earnings-call transcripts, each
+turn's text as it is spoken and then who said it. Python 3.9+.
+
+## Install
+
+```bash
+pip install live-earnings
+```
+
+## Quickstart
+
+Your API key (`ek_…`) covers one call; copy it from the call's **API Access**
+tab on https://live-earnings.com/live. Run with `LE_KEY=ek_… SLUG=<call-slug>`:
+
+```python
+import os
+
+from live_earnings import LiveEarningsClient, Transcript
+
+client = LiveEarningsClient(token=os.environ["LE_KEY"])
+slug = os.environ["SLUG"]
+transcript = Transcript()
+
+
+def show(turn):
+    if turn:
+        print(f"{turn.name or '…'}: {turn.text or ''}")
+
+
+# Everything so far, then live until the call ends.
+last = None  # the last seq seen; None = start the stream from now
+ended = False
+for env in client.events(slug):
+    show(transcript.apply(env))
+    last = env.seq
+    ended = ended or env.event.type == "done"
+if not ended:
+    for env in client.stream(slug, last_event_id=last):
+        if env.event.type == "done":
+            break
+        show(transcript.apply(env))
+```
+
+A turn prints once when its text arrives (`…: text`) and again when its
+speaker is named. `Transcript` applies the rules: a person's correction beats
+the model's name, `new_name == "unknown"` leaves a turn unnamed,
+`basis == "early"` marks a provisional name, and a repeated envelope is
+ignored. `apply()` returns the turn itself, updated in place as later
+events arrive.
+
+## The client
+
+| | |
+|---|---|
+| `meta(slug)` | the call: ticker, fiscal period, status, roster |
+| `events(slug, from_=None, to=None, limit=None)` | every stored envelope, following pagination |
+| `stream(slug, last_event_id=None)` | live envelopes; raises if the connection goes silent for 90 s — resume with the last `seq` you saw |
+| `session_token(slug)` | a `SessionToken` (`session_token`, `expires_in`) for a browser `EventSource` (`?t=`) — call it on your server |
+
+Hosts default to `https://live-earnings.com` (REST) and
+`https://stream.live-earnings.com` (streams); override with `base_url` and
+`stream_url`. Both must be `https://` unless you pass `allow_insecure=True` for
+local development. Errors raise `LiveEarningsError` (`status`, `body`).
+
+Full reference: https://live-earnings.com/live/docs
+
+## Changes
+
+**0.4.0** — Default hosts (`base_url` is optional; streams go to the stream
+host). `Transcript` folds events into turns. `session_token()`. `events()`
+takes an optional range. Streams deliver each message as it arrives (they
+were buffered in 512-byte reads). `AiInsightEvent` is deprecated — the API
+does not currently send it.
+
+**0.3.0** — `UnknownEvent.naming == "pending"` (the name follows as a
+`TurnSpeakerAmendEvent`); amends carry `by` and may carry `basis == "early"`.
+
+**0.2.0** — `stt_speaker_change` on `AttributionEvent` and `UnknownEvent`;
+`ai_insight` and `turn_speaker_amend` decode to their own classes.

live_earnings-0.4.0/README.md

@@ -0,0 +1,81 @@
+# live-earnings
+
+Python client for the Live Earnings API: live earnings-call transcripts, each
+turn's text as it is spoken and then who said it. Python 3.9+.
+
+## Install
+
+```bash
+pip install live-earnings
+```
+
+## Quickstart
+
+Your API key (`ek_…`) covers one call; copy it from the call's **API Access**
+tab on https://live-earnings.com/live. Run with `LE_KEY=ek_… SLUG=<call-slug>`:
+
+```python
+import os
+
+from live_earnings import LiveEarningsClient, Transcript
+
+client = LiveEarningsClient(token=os.environ["LE_KEY"])
+slug = os.environ["SLUG"]
+transcript = Transcript()
+
+
+def show(turn):
+    if turn:
+        print(f"{turn.name or '…'}: {turn.text or ''}")
+
+
+# Everything so far, then live until the call ends.
+last = None  # the last seq seen; None = start the stream from now
+ended = False
+for env in client.events(slug):
+    show(transcript.apply(env))
+    last = env.seq
+    ended = ended or env.event.type == "done"
+if not ended:
+    for env in client.stream(slug, last_event_id=last):
+        if env.event.type == "done":
+            break
+        show(transcript.apply(env))
+```
+
+A turn prints once when its text arrives (`…: text`) and again when its
+speaker is named. `Transcript` applies the rules: a person's correction beats
+the model's name, `new_name == "unknown"` leaves a turn unnamed,
+`basis == "early"` marks a provisional name, and a repeated envelope is
+ignored. `apply()` returns the turn itself, updated in place as later
+events arrive.
+
+## The client
+
+| | |
+|---|---|
+| `meta(slug)` | the call: ticker, fiscal period, status, roster |
+| `events(slug, from_=None, to=None, limit=None)` | every stored envelope, following pagination |
+| `stream(slug, last_event_id=None)` | live envelopes; raises if the connection goes silent for 90 s — resume with the last `seq` you saw |
+| `session_token(slug)` | a `SessionToken` (`session_token`, `expires_in`) for a browser `EventSource` (`?t=`) — call it on your server |
+
+Hosts default to `https://live-earnings.com` (REST) and
+`https://stream.live-earnings.com` (streams); override with `base_url` and
+`stream_url`. Both must be `https://` unless you pass `allow_insecure=True` for
+local development. Errors raise `LiveEarningsError` (`status`, `body`).
+
+Full reference: https://live-earnings.com/live/docs
+
+## Changes
+
+**0.4.0** — Default hosts (`base_url` is optional; streams go to the stream
+host). `Transcript` folds events into turns. `session_token()`. `events()`
+takes an optional range. Streams deliver each message as it arrives (they
+were buffered in 512-byte reads). `AiInsightEvent` is deprecated — the API
+does not currently send it.
+
+**0.3.0** — `UnknownEvent.naming == "pending"` (the name follows as a
+`TurnSpeakerAmendEvent`); amends carry `by` and may carry `basis == "early"`.
+
+**0.2.0** — `stt_speaker_change` on `AttributionEvent` and `UnknownEvent`;
+`ai_insight` and `turn_speaker_amend` decode to their own classes.

live_earnings-0.4.0/live_earnings/__init__.py

@@ -0,0 +1,53 @@
+"""Live Earnings — Python client.
+
+Public API:
+    LiveEarningsClient — the main entry point.
+    Transcript / Turn — fold envelopes into turns (text first, name after).
+    AttributionEvent / UnknownEvent / PhaseTransitionEvent / DoneEvent —
+        the event shapes you'll see when iterating client.stream().
+    EventEnvelope — the wire-level wrapper.
+    CallMeta — what client.meta() returns.
+"""
+
+from .client import LiveEarningsClient, LiveEarningsError, SessionToken, DEFAULT_BASE_URL, DEFAULT_STREAM_URL
+from .transcript import Transcript, Turn
+from .types import (
+    AttributionEvent,
+    UnknownEvent,
+    PhaseTransitionEvent,
+    DoneEvent,
+    AiInsightEvent,
+    TurnSpeakerAmendEvent,
+    AnyEvent,
+    EventEnvelope,
+    CallMeta,
+    Participant,
+    CoveringAnalyst,
+    Phase,
+    SpeakerChange,
+)
+
+__all__ = [
+    "LiveEarningsClient",
+    "LiveEarningsError",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_STREAM_URL",
+    "Transcript",
+    "Turn",
+    "SessionToken",
+    "AttributionEvent",
+    "UnknownEvent",
+    "PhaseTransitionEvent",
+    "DoneEvent",
+    "AiInsightEvent",
+    "TurnSpeakerAmendEvent",
+    "AnyEvent",
+    "EventEnvelope",
+    "CallMeta",
+    "Participant",
+    "CoveringAnalyst",
+    "Phase",
+    "SpeakerChange",
+]
+
+__version__ = "0.4.0"

live_earnings-0.4.0/live_earnings/client.py

@@ -0,0 +1,295 @@
+"""Live Earnings client.
+
+The full API surface is on `LiveEarningsClient`:
+
+    .meta(call_slug)            → CallMeta
+    .events(call_slug)          → iterator of EventEnvelope (stored history)
+    .stream(call_slug)          → iterator of EventEnvelope (live SSE)
+    .session_token(call_slug)   → a 2-hour token for browser streams
+
+Two hosts: REST on https://live-earnings.com, streams on
+https://stream.live-earnings.com (a stream requested on the REST host answers
+503). Auth is the subscriber key (`ek_*`) as a Bearer header.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Iterator, Optional
+from urllib.parse import urlparse
+
+import requests
+
+from .types import (
+    CallMeta,
+    EventEnvelope,
+    parse_envelope,
+    parse_meta,
+)
+
+#: The REST host: /meta, /events, /sections, /report, /session-token.
+DEFAULT_BASE_URL = "https://live-earnings.com"
+#: The stream host: /stream, /partial-stream, /audio-stream.
+DEFAULT_STREAM_URL = "https://stream.live-earnings.com"
+DEFAULT_TIMEOUT = 30
+#: Give up on a stream that sends nothing (not even the 25 s heartbeat) for
+#: this long: it raises, so the caller can reconnect with last_event_id.
+STREAM_IDLE_TIMEOUT = 90
+
+
+@dataclass
+class SessionToken:
+    """A short-lived token for opening a stream as `?t=<session_token>`."""
+
+    session_token: str
+    #: Seconds (7200).
+    expires_in: int
+
+
+def _host(url: str, allow_insecure: bool, what: str) -> str:
+    parsed = urlparse(url)
+    if not parsed.netloc:
+        raise ValueError(f"{what} is not a URL: {url}")
+    if parsed.scheme != "https" and not (allow_insecure and parsed.scheme == "http"):
+        # Every request carries the key: it must not travel in clear text.
+        raise ValueError(f"{what} must be https:// (pass allow_insecure=True for local http://)")
+    return url.rstrip("/")
+
+
+class LiveEarningsError(Exception):
+    """Raised on 4xx / 5xx responses.
+
+    `status` carries the HTTP code; `body` is the response body if any.
+    """
+
+    def __init__(self, status: int, body: str = ""):
+        self.status = status
+        self.body = body
+        super().__init__(f"Live Earnings API error: {status} — {body[:200]}")
+
+
+def _sse_lines(r: requests.Response) -> Iterator[str]:
+    """The response's lines as they arrive, decoded as UTF-8.
+
+    Reads chunks as they come (chunk_size=None; a fixed size would hold short
+    envelopes and heartbeats back) and splits on "\\n" only — requests'
+    iter_lines uses str.splitlines, which also breaks on U+2028/U+0085 (legal,
+    unescaped, inside JSON strings) and on a CRLF split across chunks.
+    """
+    buf = b""
+    for chunk in r.iter_content(chunk_size=None):
+        buf += chunk
+        while True:
+            i = buf.find(b"\n")
+            if i < 0:
+                break
+            line, buf = buf[:i], buf[i + 1 :]
+            yield line.rstrip(b"\r").decode("utf-8", errors="replace")
+    if buf:
+        yield buf.rstrip(b"\r").decode("utf-8", errors="replace")
+
+
+class LiveEarningsClient:
+    """Live Earnings — REST + SSE client.
+
+    Example:
+        >>> client = LiveEarningsClient(token="ek_...")
+        >>> transcript = Transcript()
+        >>> for env in client.stream("nvda-q3-fy27"):
+        ...     turn = transcript.apply(env)
+        ...     if turn:
+        ...         print(turn.name or "…", turn.text)
+
+    Parameters
+    ----------
+    token : str
+        Your subscriber API key (`ek_*`). Scoped to one call slug;
+        cross-call use returns 401.
+    base_url : str, optional
+        REST host. Defaults to DEFAULT_BASE_URL.
+    stream_url : str, optional
+        Stream host. Defaults to DEFAULT_STREAM_URL.
+    allow_insecure : bool, optional
+        Allow http:// hosts (local development only).
+    timeout : int, optional
+        Per-request timeout in seconds for REST endpoints. SSE
+        streams use no timeout (they're long-lived by design).
+    """
+
+    def __init__(
+        self,
+        token: str,
+        base_url: Optional[str] = None,
+        stream_url: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        allow_insecure: bool = False,
+    ):
+        if not token:
+            raise ValueError("token is required")
+        self._token = token
+        self._base = _host(base_url or DEFAULT_BASE_URL, allow_insecure, "base_url")
+        self._stream_base = _host(stream_url or DEFAULT_STREAM_URL, allow_insecure, "stream_url")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers["Authorization"] = f"Bearer {token}"
+
+    # ── meta ──────────────────────────────────────────────────────
+
+    def meta(self, call_slug: str) -> CallMeta:
+        """Fetch call metadata: ticker, status, roster, participants.
+
+        Call once on bootstrap. If you observe an envelope with
+        type='done', consider re-fetching to pick up the final
+        status='ended'.
+        """
+        r = self._session.get(
+            f"{self._base}/api/live/{call_slug}/meta",
+            timeout=self._timeout,
+        )
+        self._check(r)
+        return parse_meta(r.json())
+
+    # ── session token (browser streams) ──────────────────────────
+
+    def session_token(self, call_slug: str) -> SessionToken:
+        """A short-lived token for a stream opened where headers cannot be sent
+        (a browser's EventSource): `{stream_url}/api/live/{slug}/stream?t=<token>`.
+
+        It is checked when a stream opens; mint a fresh one before reconnecting
+        after expires_in seconds.
+        """
+        r = self._session.post(
+            f"{self._base}/api/live/{call_slug}/session-token",
+            timeout=self._timeout,
+        )
+        self._check(r)
+        body = r.json()
+        return SessionToken(session_token=body["sessionToken"], expires_in=int(body["expiresIn"]))
+
+    # ── events backfill ──────────────────────────────────────────
+
+    def events(
+        self,
+        call_slug: str,
+        from_: Optional[int] = None,
+        to: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[EventEnvelope]:
+        """Iterate the stored event log, oldest first (default: all of it).
+
+        Paginates internally, following `nextFrom`. Each request fetches at
+        most `limit` envelopes (server default 1000, max 5000).
+        """
+        cursor = from_
+        while True:
+            params = {k: v for k, v in (("from", cursor), ("to", to), ("limit", limit)) if v is not None}
+            r = self._session.get(
+                f"{self._base}/api/live/{call_slug}/events",
+                params=params,
+                timeout=self._timeout,
+            )
+            self._check(r)
+            body = r.json()
+            for e in body.get("events", []):
+                yield parse_envelope(e)
+            # nextFrom, not an empty page, says when to stop: a page can be
+            # empty when every event in it is one subscribers are not sent.
+            next_from = body.get("nextFrom")
+            if next_from is None:
+                return
+            if cursor is not None and next_from <= cursor:
+                raise LiveEarningsError(0, f"events paging did not advance (nextFrom {next_from} after from {cursor})")
+            cursor = next_from
+
+    # ── live SSE stream ──────────────────────────────────────────
+
+    def stream(
+        self,
+        call_slug: str,
+        last_event_id: Optional[int] = None,
+    ) -> Iterator[EventEnvelope]:
+        """Iterate envelopes as they arrive live.
+
+        Generator yields one EventEnvelope per server event. Auto-handles
+        the SSE framing (`id:` / `event:` / `data:` lines).
+
+        Reconnect logic is YOUR responsibility — if this iterator raises or
+        ends before `done`, call .stream() again with the last `env.seq` you
+        saw as `last_event_id`: the server replays what you missed. An
+        envelope near the reconnect can arrive twice; Transcript ignores
+        repeats.
+
+        Parameters
+        ----------
+        last_event_id : int, optional
+            The last seq you saw; the server replays everything after it.
+            Omit it when you have seen nothing yet — the stream then starts
+            from now, so read history first with events().
+
+        A connection silent for STREAM_IDLE_TIMEOUT seconds raises
+        LiveEarningsError, like any other failure, so one handler can
+        reconnect.
+        """
+        headers = {"Accept": "text/event-stream"}
+        if last_event_id is not None:
+            headers["Last-Event-ID"] = str(last_event_id)
+
+        # The connection lasts the whole call, so there is no total timeout —
+        # only a read timeout: a connection silent past several heartbeats is
+        # dead, and raising lets the caller reconnect.
+        try:
+            yield from self._stream(call_slug, headers)
+        except requests.exceptions.RequestException as e:
+            # requests reports a read timeout as ConnectionError; surface every
+            # transport failure as the SDK's own error.
+            raise LiveEarningsError(0, f"stream failed: {e}") from e
+
+    def _stream(self, call_slug: str, headers: dict) -> Iterator[EventEnvelope]:
+        with self._session.get(
+            f"{self._stream_base}/api/live/{call_slug}/stream",
+            headers=headers,
+            stream=True,
+            timeout=(10, STREAM_IDLE_TIMEOUT),
+        ) as r:
+            self._check(r)
+            event_name = "envelope"
+            data_buf: list[str] = []
+            # Iterate line-by-line. SSE separates events with a blank
+            # line; we accumulate `data:` lines and dispatch on blank.
+            for line in _sse_lines(r):
+                if line == "":
+                    # Dispatch the accumulated event.
+                    if data_buf and event_name == "envelope":
+                        payload = "\n".join(data_buf)
+                        try:
+                            yield parse_envelope(json.loads(payload))
+                        except (ValueError, KeyError) as e:
+                            # Malformed payload — skip rather than
+                            # killing the iterator. Surface via stderr.
+                            import sys
+                            print(
+                                f"[live-earnings] malformed envelope: {e}",
+                                file=sys.stderr,
+                            )
+                    event_name = "envelope"
+                    data_buf = []
+                    continue
+                if line.startswith(":"):
+                    # Comment / heartbeat line — ignore.
+                    continue
+                if line.startswith("event:"):
+                    event_name = line[6:].strip()
+                elif line.startswith("data:"):
+                    data_buf.append(line[5:].lstrip())
+                elif line.startswith("id:"):
+                    # We don't track this explicitly — the env.seq we
+                    # parse from `data:` is the same value.
+                    pass
+
+    # ── helpers ──────────────────────────────────────────────────
+
+
+    def _check(self, r: requests.Response) -> None:
+        if r.status_code >= 400:
+            raise LiveEarningsError(r.status_code, r.text)

live_earnings-0.4.0/live_earnings/transcript.py

@@ -0,0 +1,89 @@
+"""Transcript — folds the event stream into turns: the text first, the name after.
+
+A turn's text usually arrives as an `unknown` event (naming "pending") and its
+speaker follows as a `turn_speaker_amend`. Some calls publish text and name
+together as an `attribution`. Feed every envelope — from client.events() and
+client.stream() — to apply(); it returns the turn it changed.
+
+Rules: a person's correction (amend with `by` absent or "operator") always beats
+the model's name, whatever order they arrive in. new_name "unknown" means the
+turn stays unnamed. basis "early" marks a provisional name. An envelope seen
+twice (a stream replay after reconnecting can repeat one) is ignored.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Dict, List, Literal, Optional, Set
+
+from .types import EventEnvelope, Phase
+
+
+@dataclass
+class Turn:
+    turn_id: str
+    #: The turn's text; None if only its name has arrived so far.
+    text: Optional[str] = None
+    #: Who spoke; None while unnamed.
+    name: Optional[str] = None
+    #: Where the name came from: a person's correction, the model, or an
+    #: `attribution` (text and name published together).
+    named_by: Optional[Literal["operator", "model", "attribution"]] = None
+    #: A provisional name (from the turn's first sentence only).
+    provisional: bool = False
+    phase: Optional[Phase] = None
+
+
+def _turn_number(turn_id: str) -> int:
+    m = re.search(r"-(\d+)$", turn_id)
+    return int(m.group(1)) if m else 2**62
+
+
+class Transcript:
+    def __init__(self) -> None:
+        self._by_id: Dict[str, Turn] = {}
+        self._seen: Set[int] = set()
+
+    def apply(self, env: EventEnvelope) -> Optional[Turn]:
+        """Apply one envelope. Returns the turn it changed, or None."""
+        if env.seq in self._seen:
+            return None
+        self._seen.add(env.seq)
+        ev = env.event
+        if ev.type in ("unknown", "attribution"):
+            t = self._turn(ev.turn_id)
+            if ev.text is not None:
+                t.text = ev.text
+            if ev.phase is not None:
+                t.phase = ev.phase
+            if ev.type == "attribution" and t.named_by != "operator":
+                t.name = ev.name
+                t.named_by = "attribution"
+                t.provisional = False
+            return t
+        if ev.type == "turn_speaker_amend":
+            t = self._turn(ev.turn_id)
+            human = ev.by != "model"
+            if not human and t.named_by == "operator":
+                return None  # a correction stands
+            t.name = None if ev.new_name == "unknown" else ev.new_name
+            t.named_by = "operator" if human else "model"
+            t.provisional = ev.basis == "early"
+            return t
+        return None
+
+    @property
+    def turns(self) -> List[Turn]:
+        """Every turn so far, in the order they were spoken."""
+        return sorted(self._by_id.values(), key=lambda t: _turn_number(t.turn_id))
+
+    def get(self, turn_id: str) -> Optional[Turn]:
+        return self._by_id.get(turn_id)
+
+    def _turn(self, turn_id: str) -> Turn:
+        t = self._by_id.get(turn_id)
+        if t is None:
+            t = Turn(turn_id=turn_id)
+            self._by_id[turn_id] = t
+        return t

live_earnings-0.4.0/live_earnings/types.py

@@ -0,0 +1,313 @@
+"""Wire-format types — match the public OpenAPI / AsyncAPI specs.
+
+Everything is a `dataclass` so users can pattern-match via
+`isinstance(ev, AttributionEvent)` and IDEs autocomplete the fields.
+
+Decoded events normalize JSON keys to snake_case. The original
+JSON dict is preserved on each instance as `.raw` for advanced
+consumers (e.g., new optional fields we don't know about yet).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional, Union
+
+Phase = Literal[
+    "unknown",
+    "operator_opening",
+    "ir_intro",
+    "cfo_remarks",
+    "ceo_remarks",
+    "qa",
+    "closing",
+]
+
+# The speech engine's observation that a turn's speaker is the SAME as the
+# previous turn's, NEW, or "unknown" when it cannot tell. Only the Meta Muse
+# engine observes it (the default engine); AssemblyAI calls are always "unknown", as
+# is the first turn on each new Muse connection and a turn right after an
+# unlabelled one. It
+# is what the engine heard, not truth, and never an input to the speaker
+# name. "same" means "same as the turn just before": if you did not receive
+# the turn with the previous turn number (turn_id "<slug>-<n-1>"), treat it
+# as "unknown". Measured on two calls: every real speaker change was marked
+# "new" (104 of 104) — counting the changes that fell on a turn boundary; Muse merged 3 of TTWO's 76 into the previous turn, and those carry no mark —, so a "same" mark was never wrong (176 of 176); "new"
+# was right about 94% of the time on turns of more than 5 words (101 of
+# 108), but only 3 of 17 on turns of 5 words or fewer.
+SpeakerChange = Literal["same", "new", "unknown"]
+
+
+@dataclass
+class AttributionEvent:
+    """A finalized speaker turn with a confident attribution."""
+
+    turn_id: str
+    name: str
+    source: str  # always "live-earnings" — internal pipeline labels stripped
+    text: Optional[str] = None
+    phase: Optional[Phase] = None
+    stt_speaker_change: SpeakerChange = "unknown"
+    raw: dict = field(default_factory=dict, repr=False)
+    type: Literal["attribution"] = "attribution"
+
+
+@dataclass
+class UnknownEvent:
+    """A finalized turn with no speaker name (yet).
+
+    naming == "pending": published before its name arrived; the name follows
+    as a TurnSpeakerAmendEvent with by == "model" (new_name "unknown" when it
+    could not be named). Otherwise the turn simply could not be attributed.
+    """
+
+    turn_id: str
+    text: Optional[str] = None
+    phase: Optional[Phase] = None
+    stt_speaker_change: SpeakerChange = "unknown"
+    naming: Optional[Literal["pending"]] = None
+    raw: dict = field(default_factory=dict, repr=False)
+    type: Literal["unknown"] = "unknown"
+
+
+@dataclass
+class PhaseTransitionEvent:
+    """The call moved from one phase (e.g., CFO remarks) to the next (Q&A)."""
+
+    from_phase: Phase
+    to_phase: Phase
+    trigger_turn_id: str
+    raw: dict = field(default_factory=dict, repr=False)
+    type: Literal["phase_transition"] = "phase_transition"
+
+
+@dataclass
+class DoneEvent:
+    """The call has ended; no more envelopes will follow."""
+
+    raw: dict = field(default_factory=dict, repr=False)
+    type: Literal["done"] = "done"
+
+
+@dataclass
+class AiInsightEvent:
+    """Deprecated: AI insights are withdrawn while they are rebuilt, and the API
+    does not currently send this event. Kept so code written against it runs."""
+
+    turn_id: str
+    insight: str
+    category: str  # e.g. "guidance", "cfo_numbers"; new values may appear
+    frame: Optional[str] = None
+    watch_for: Optional[str] = None
+    raw: dict = field(default_factory=dict, repr=False)
+    type: Literal["ai_insight"] = "ai_insight"
+
+
+@dataclass
+class TurnSpeakerAmendEvent:
+    """A published turn's speaker, set or corrected after publish: show
+    `new_name` for that turn_id, at the turn's original position.
+
+    by == "model": the model's late name (new_name "unknown" = could not be
+    named). by None or "operator": an operator's correction, which always
+    wins over the model's whatever order they arrive in.
+
+    basis == "early": the model's full-text naming failed; this is the
+    turn's early, first-sentence name, kept. Show it as provisional."""
+
+    turn_id: str
+    new_name: str
+    reason: Optional[str] = None
+    by: Optional[Literal["model", "operator"]] = None
+    basis: Optional[Literal["early"]] = None
+    raw: dict = field(default_factory=dict, repr=False)
+    type: Literal["turn_speaker_amend"] = "turn_speaker_amend"
+
+
+AnyEvent = Union[
+    AttributionEvent,
+    UnknownEvent,
+    PhaseTransitionEvent,
+    DoneEvent,
+    AiInsightEvent,
+    TurnSpeakerAmendEvent,
+]
+
+
+@dataclass
+class EventEnvelope:
+    """SSE envelope wrapping one event.
+
+    `seq` increases per (tenant, call), but numbers are skipped (internal
+    events are not sent): a missing number is not a lost event.
+    """
+
+    tenant_id: str
+    call_slug: str
+    seq: int
+    published_at: str  # ISO-8601 UTC
+    event: AnyEvent
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class Participant:
+    name: str
+    title: Optional[str] = None
+    avatar_url: Optional[str] = None
+    role: Optional[Literal["ceo", "cfo", "ir"]] = None
+    brain_slug: Optional[str] = None
+
+
+@dataclass
+class CoveringAnalyst:
+    name: str
+    firm: Optional[str] = None
+    firm_domain: Optional[str] = None
+
+
+@dataclass
+class Roster:
+    ceo: Optional[str]
+    cfo: Optional[str]
+    ir: Optional[str]
+    extras: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CallMeta:
+    call_slug: str
+    tenant_id: str
+    ticker: Optional[str]
+    fiscal_period: Optional[str]
+    status: Literal["scheduled", "live", "ended", "unknown"]
+    elapsed_sec: Optional[int]
+    roster: Optional[Roster]
+    participants: list[Participant] = field(default_factory=list)
+    covering_analysts: list[CoveringAnalyst] = field(default_factory=list)
+    roster_source: Optional[Literal["db", "none", "error"]] = None
+    roster_updated_at: Optional[str] = None
+    # Operator-auth responses only (never sent to subscribers):
+    stt_engine: Optional[str] = None  # "aai" | "muse" | a raw invalid value
+    stt_engine_source: Optional[Literal["row", "default", "invalid"]] = None
+    roster_problems: Optional[list[str]] = None
+    operator_audio_url: Optional[str] = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+
+def parse_event(d: dict) -> AnyEvent:
+    """Decode the inner `event` dict from a /stream envelope."""
+    t = d.get("type")
+    if t == "attribution":
+        return AttributionEvent(
+            turn_id=d["turnId"],
+            name=d["name"],
+            source=d.get("source", "live-earnings"),
+            text=d.get("text"),
+            phase=d.get("phase"),
+            stt_speaker_change=d.get("sttSpeakerChange", "unknown"),
+            raw=d,
+        )
+    if t == "unknown":
+        return UnknownEvent(
+            turn_id=d["turnId"],
+            text=d.get("text"),
+            phase=d.get("phase"),
+            stt_speaker_change=d.get("sttSpeakerChange", "unknown"),
+            naming=d.get("naming"),
+            raw=d,
+        )
+    if t == "ai_insight":
+        return AiInsightEvent(
+            turn_id=d["turnId"],
+            insight=d["insight"],
+            category=d.get("category", "general"),
+            frame=d.get("frame"),
+            watch_for=d.get("watchFor"),
+            raw=d,
+        )
+    if t == "turn_speaker_amend":
+        return TurnSpeakerAmendEvent(
+            turn_id=d["turnId"],
+            new_name=d["newName"],
+            reason=d.get("reason"),
+            by=d.get("by"),
+            basis=d.get("basis"),
+            raw=d,
+        )
+    if t == "phase_transition":
+        return PhaseTransitionEvent(
+            from_phase=d["fromPhase"],
+            to_phase=d["toPhase"],
+            trigger_turn_id=d["triggerTurnId"],
+            raw=d,
+        )
+    if t == "done":
+        return DoneEvent(raw=d)
+    # Forward-compatible: unknown event types degrade to UnknownEvent
+    # rather than throw. The full dict is preserved on `.raw`.
+    return UnknownEvent(turn_id=d.get("turnId", ""), text=None, raw=d)
+
+
+def parse_envelope(d: dict) -> EventEnvelope:
+    return EventEnvelope(
+        tenant_id=d["tenantId"],
+        call_slug=d["callSlug"],
+        seq=d["seq"],
+        published_at=d["publishedAt"],
+        event=parse_event(d["event"]),
+        raw=d,
+    )
+
+
+def parse_meta(d: dict) -> CallMeta:
+    roster_raw = d.get("roster")
+    roster = (
+        Roster(
+            ceo=roster_raw.get("ceo"),
+            cfo=roster_raw.get("cfo"),
+            ir=roster_raw.get("ir"),
+            extras=list(roster_raw.get("extras", [])),
+        )
+        if roster_raw
+        else None
+    )
+    return CallMeta(
+        call_slug=d["callSlug"],
+        tenant_id=d["tenantId"],
+        ticker=d.get("ticker"),
+        fiscal_period=d.get("fiscalPeriod"),
+        status=d.get("status", "unknown"),
+        elapsed_sec=d.get("elapsedSec"),
+        roster=roster,
+        participants=[
+            Participant(
+                name=p["name"],
+                title=p.get("title"),
+                avatar_url=p.get("avatarUrl"),
+                role=p.get("role"),
+                brain_slug=p.get("brainSlug"),
+            )
+            for p in d.get("participants", [])
+        ],
+        covering_analysts=[
+            CoveringAnalyst(
+                name=a["name"],
+                firm=a.get("firm"),
+                firm_domain=a.get("firmDomain"),
+            )
+            for a in d.get("coveringAnalysts", [])
+        ],
+        roster_source=d.get("rosterSource"),
+        roster_updated_at=d.get("rosterUpdatedAt"),
+        stt_engine=d.get("sttEngine"),
+        stt_engine_source=d.get("sttEngineSource"),
+        roster_problems=d.get("rosterProblems"),
+        operator_audio_url=d.get("operatorAudioUrl"),
+        raw=d,
+    )
+
+
+def _decode_any(d: Any) -> Any:
+    """Reserved for future shape evolution."""
+    return d

live_earnings-0.4.0/live_earnings.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: live-earnings
+Version: 0.4.0
+Summary: Live Earnings — live, attributed earnings-call transcripts.
+Author: Live Earnings
+License: Proprietary
+Project-URL: Homepage, https://live-earnings.com/live/docs
+Project-URL: Documentation, https://live-earnings.com/live/docs
+Project-URL: Source, https://live-earnings.com/live/docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+
+# live-earnings
+
+Python client for the Live Earnings API: live earnings-call transcripts, each
+turn's text as it is spoken and then who said it. Python 3.9+.
+
+## Install
+
+```bash
+pip install live-earnings
+```
+
+## Quickstart
+
+Your API key (`ek_…`) covers one call; copy it from the call's **API Access**
+tab on https://live-earnings.com/live. Run with `LE_KEY=ek_… SLUG=<call-slug>`:
+
+```python
+import os
+
+from live_earnings import LiveEarningsClient, Transcript
+
+client = LiveEarningsClient(token=os.environ["LE_KEY"])
+slug = os.environ["SLUG"]
+transcript = Transcript()
+
+
+def show(turn):
+    if turn:
+        print(f"{turn.name or '…'}: {turn.text or ''}")
+
+
+# Everything so far, then live until the call ends.
+last = None  # the last seq seen; None = start the stream from now
+ended = False
+for env in client.events(slug):
+    show(transcript.apply(env))
+    last = env.seq
+    ended = ended or env.event.type == "done"
+if not ended:
+    for env in client.stream(slug, last_event_id=last):
+        if env.event.type == "done":
+            break
+        show(transcript.apply(env))
+```
+
+A turn prints once when its text arrives (`…: text`) and again when its
+speaker is named. `Transcript` applies the rules: a person's correction beats
+the model's name, `new_name == "unknown"` leaves a turn unnamed,
+`basis == "early"` marks a provisional name, and a repeated envelope is
+ignored. `apply()` returns the turn itself, updated in place as later
+events arrive.
+
+## The client
+
+| | |
+|---|---|
+| `meta(slug)` | the call: ticker, fiscal period, status, roster |
+| `events(slug, from_=None, to=None, limit=None)` | every stored envelope, following pagination |
+| `stream(slug, last_event_id=None)` | live envelopes; raises if the connection goes silent for 90 s — resume with the last `seq` you saw |
+| `session_token(slug)` | a `SessionToken` (`session_token`, `expires_in`) for a browser `EventSource` (`?t=`) — call it on your server |
+
+Hosts default to `https://live-earnings.com` (REST) and
+`https://stream.live-earnings.com` (streams); override with `base_url` and
+`stream_url`. Both must be `https://` unless you pass `allow_insecure=True` for
+local development. Errors raise `LiveEarningsError` (`status`, `body`).
+
+Full reference: https://live-earnings.com/live/docs
+
+## Changes
+
+**0.4.0** — Default hosts (`base_url` is optional; streams go to the stream
+host). `Transcript` folds events into turns. `session_token()`. `events()`
+takes an optional range. Streams deliver each message as it arrives (they
+were buffered in 512-byte reads). `AiInsightEvent` is deprecated — the API
+does not currently send it.
+
+**0.3.0** — `UnknownEvent.naming == "pending"` (the name follows as a
+`TurnSpeakerAmendEvent`); amends carry `by` and may carry `basis == "early"`.
+
+**0.2.0** — `stt_speaker_change` on `AttributionEvent` and `UnknownEvent`;
+`ai_insight` and `turn_speaker_amend` decode to their own classes.

live_earnings-0.4.0/live_earnings.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+live_earnings/__init__.py
+live_earnings/client.py
+live_earnings/transcript.py
+live_earnings/types.py
+live_earnings.egg-info/PKG-INFO
+live_earnings.egg-info/SOURCES.txt
+live_earnings.egg-info/dependency_links.txt
+live_earnings.egg-info/requires.txt
+live_earnings.egg-info/top_level.txt
+tests/test_sdk.py

live_earnings-0.4.0/live_earnings.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

live_earnings-0.4.0/live_earnings.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.31

live_earnings-0.4.0/live_earnings.egg-info/top_level.txt

@@ -0,0 +1 @@
+live_earnings

live_earnings-0.4.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "live-earnings"
+version = "0.4.0"
+description = "Live Earnings — live, attributed earnings-call transcripts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Proprietary" }
+authors = [{ name = "Live Earnings" }]
+dependencies = ["requests>=2.31"]
+
+[project.urls]
+Homepage = "https://live-earnings.com/live/docs"
+Documentation = "https://live-earnings.com/live/docs"
+Source = "https://live-earnings.com/live/docs"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["live_earnings*"]

live_earnings-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

live_earnings-0.4.0/tests/test_sdk.py

@@ -0,0 +1,194 @@
+"""Python SDK: hosts, the https guard, and the Transcript fold.
+
+Run: cd sdks/python && python3 -m unittest discover -s tests
+"""
+
+import unittest
+
+from live_earnings import DEFAULT_BASE_URL, DEFAULT_STREAM_URL, LiveEarningsClient, Transcript
+from live_earnings.types import parse_envelope
+
+
+def env(seq, event):
+    return parse_envelope({"tenantId": "t", "callSlug": "s", "seq": seq, "publishedAt": "1970-01-01T00:00:00Z", "event": event})
+
+
+def unk(n, text=None):
+    return {"type": "unknown", "turnId": f"s-{n}", "text": text or f"turn {n} text", "sttSpeakerChange": "new", "naming": "pending"}
+
+
+def amend(n, name, **extra):
+    return {"type": "turn_speaker_amend", "turnId": f"s-{n}", "newName": name, **extra}
+
+
+def attribution(n, name, text="final"):
+    return {"type": "attribution", "turnId": f"s-{n}", "name": name, "source": "live-earnings", "text": text, "sttSpeakerChange": "same"}
+
+
+class Hosts(unittest.TestCase):
+    def test_defaults_to_the_two_production_hosts(self):
+        self.assertEqual(DEFAULT_BASE_URL, "https://live-earnings.com")
+        self.assertEqual(DEFAULT_STREAM_URL, "https://stream.live-earnings.com")
+        c = LiveEarningsClient(token="ek_test")
+        self.assertEqual(c._base, "https://live-earnings.com")
+        self.assertEqual(c._stream_base, "https://stream.live-earnings.com")
+
+    def test_refuses_http_unless_allowed(self):
+        with self.assertRaises(ValueError):
+            LiveEarningsClient(token="t", base_url="http://live-earnings.com")
+        with self.assertRaises(ValueError):
+            LiveEarningsClient(token="t", stream_url="http://x.test")
+        with self.assertRaises(ValueError):
+            LiveEarningsClient(token="t", base_url="not a url")
+        LiveEarningsClient(token="t", base_url="http://localhost:3000", stream_url="http://localhost:3000", allow_insecure=True)
+
+
+class _FakeResponse:
+    def __init__(self, chunks):
+        self._chunks = chunks
+
+    def iter_content(self, chunk_size=None):
+        yield from self._chunks
+
+
+class StreamLines(unittest.TestCase):
+    def test_lines_split_on_newline_only_as_utf8(self):
+        from live_earnings.client import _sse_lines
+
+        # A CRLF split across chunks, a multi-byte character split across chunks,
+        # and U+2028 inside a JSON string (str.splitlines would break there).
+        text = 'data: {"text":"a
b — ’"}\r\n\r\n: hb\n'.encode("utf-8")
+        chunks = [text[:26], text[26:27], text[27:40], text[40:]]
+        self.assertEqual(list(_sse_lines(_FakeResponse(chunks))), ['data: {"text":"a
b — ’"}', "", ": hb"])
+
+    def test_session_token_is_a_snake_case_dataclass(self):
+        from live_earnings import SessionToken
+
+        c = LiveEarningsClient(token="t")
+
+        class R:
+            status_code = 200
+
+            def json(self):
+                return {"sessionToken": "abc", "expiresIn": 7200}
+
+        c._session.post = lambda *a, **k: R()
+        self.assertEqual(c.session_token("s"), SessionToken(session_token="abc", expires_in=7200))
+
+
+class _Json:
+    status_code = 200
+
+    def __init__(self, body):
+        self._body = body
+
+    def json(self):
+        return self._body
+
+
+class Paging(unittest.TestCase):
+    def test_keeps_paging_past_an_empty_page_while_next_from_says_there_is_more(self):
+        pages = {None: {"events": [], "nextFrom": 1001}, 1001: {"events": [{"tenantId": "t", "callSlug": "s", "seq": 1001, "publishedAt": "x", "event": unk(1)}], "nextFrom": None}}
+        c = LiveEarningsClient(token="t")
+        c._session.get = lambda url, params=None, **k: _Json(pages[params.get("from")])
+        self.assertEqual([e.seq for e in c.events("s")], [1001])
+
+    def test_refuses_a_next_from_that_does_not_advance(self):
+        from live_earnings import LiveEarningsError
+
+        calls = []
+
+        def get(url, params=None, **k):
+            calls.append(params)
+            if len(calls) > 3:
+                raise AssertionError("paged forever on a nextFrom that never advances")
+            return _Json({"events": [], "nextFrom": 5})
+
+        c = LiveEarningsClient(token="t")
+        c._session.get = get
+        with self.assertRaises(LiveEarningsError):
+            list(c.events("s", from_=5))
+
+
+class StreamFailures(unittest.TestCase):
+    def test_sets_a_read_timeout_and_raises_the_sdk_error_when_it_fires(self):
+        import requests
+
+        from live_earnings import LiveEarningsError
+        from live_earnings.client import STREAM_IDLE_TIMEOUT
+
+        seen = {}
+
+        def get(url, **k):
+            seen.update(k)
+            raise requests.exceptions.ConnectionError("Read timed out.")
+
+        c = LiveEarningsClient(token="t")
+        c._session.get = get
+        with self.assertRaises(LiveEarningsError):
+            list(c.stream("s"))
+        self.assertEqual(seen["timeout"], (10, STREAM_IDLE_TIMEOUT))
+        self.assertNotIn("Last-Event-ID", seen["headers"])
+
+
+class TranscriptFold(unittest.TestCase):
+    def test_text_first_then_the_models_name(self):
+        t = Transcript()
+        first = t.apply(env(1, unk(1)))
+        self.assertEqual((first.text, first.name), ("turn 1 text", None))
+        named = t.apply(env(2, amend(1, "Colette Kress", by="model")))
+        self.assertEqual((named.name, named.named_by, named.provisional), ("Colette Kress", "model", False))
+
+    def test_a_persons_correction_beats_the_model_in_either_order(self):
+        a = Transcript()
+        a.apply(env(1, unk(1)))
+        a.apply(env(2, amend(1, "Jensen Huang")))  # by absent = operator
+        self.assertIsNone(a.apply(env(3, amend(1, "Colette Kress", by="model"))))
+        self.assertEqual(a.get("s-1").name, "Jensen Huang")
+        b = Transcript()
+        b.apply(env(1, unk(1)))
+        b.apply(env(2, amend(1, "Colette Kress", by="model")))
+        b.apply(env(3, amend(1, "Jensen Huang", by="operator")))
+        self.assertEqual((b.get("s-1").name, b.get("s-1").named_by), ("Jensen Huang", "operator"))
+
+    def test_unknown_name_and_early_basis(self):
+        t = Transcript()
+        t.apply(env(1, unk(1)))
+        self.assertIsNone(t.apply(env(2, amend(1, "unknown", by="model"))).name)
+        t.apply(env(3, unk(2)))
+        self.assertTrue(t.apply(env(4, amend(2, "Colette Kress", by="model", basis="early"))).provisional)
+
+    def test_attribution_sets_both_and_clears_provisional_but_not_over_a_correction(self):
+        t = Transcript()
+        t.apply(env(1, unk(1)))
+        t.apply(env(2, amend(1, "Colette Kress", by="model", basis="early")))
+        t.apply(env(3, attribution(1, "Jensen Huang")))
+        turn = t.get("s-1")
+        self.assertEqual((turn.name, turn.named_by, turn.provisional, turn.text), ("Jensen Huang", "attribution", False, "final"))
+        t.apply(env(4, amend(1, "Stacy Rasgon")))
+        t.apply(env(5, attribution(1, "Jensen Huang")))
+        self.assertEqual(t.get("s-1").name, "Stacy Rasgon")
+
+    def test_a_repeated_envelope_is_ignored(self):
+        t = Transcript()
+        t.apply(env(1, unk(1)))
+        self.assertIsNone(t.apply(env(1, unk(1, "different"))))
+        self.assertEqual(t.get("s-1").text, "turn 1 text")
+
+    def test_a_name_before_its_text_and_turns_in_spoken_order(self):
+        t = Transcript()
+        t.apply(env(5, amend(10, "Colette Kress", by="model")))
+        t.apply(env(6, unk(10)))
+        t.apply(env(7, unk(2)))
+        self.assertEqual((t.get("s-10").name, t.get("s-10").text), ("Colette Kress", "turn 10 text"))
+        self.assertEqual([x.turn_id for x in t.turns], ["s-2", "s-10"])
+
+    def test_other_events_change_nothing(self):
+        t = Transcript()
+        self.assertIsNone(t.apply(env(1, {"type": "phase_transition", "fromPhase": "ir_intro", "toPhase": "qa", "triggerTurnId": "s-1"})))
+        self.assertIsNone(t.apply(env(2, {"type": "done"})))
+        self.assertEqual(t.turns, [])
+
+
+if __name__ == "__main__":
+    unittest.main()