# -*- coding: utf-8 -*-
"""The Brief, rendered as the published research note.
One document, ten sections, a sticky contents bar, a sticky data rail and a
sourced footer — the same structure, in the same order, with the same classes
and the same palette as the artifact this design was taken from
(https://claude.ai/code/artifact/a552e2bc-add9-48ea-b706-4b95f122d0e5).
Two rules hold the whole file together.
**Every section keeps its slot.** A section whose data the corpus does not
hold still prints its eyebrow, its heading and a sentence saying so. Sections
that disappear when empty would move every heading below them, and the layout
is part of what is being reproduced.
**Every fact keeps its tag.** Numbers reach the page through
``dashboard.note_data``, which knows whether a quarter was filed or derived,
and each claim carries the source it was read from plus that source's
reliability — the ``.src``/``.rel`` pair the note uses everywhere. Nothing is
printed that cannot say where it came from.
``build`` is a pure function returning HTML, so the document can be asserted
in tests without a Streamlit runtime. ``render`` is the Streamlit entry point.
"""
from __future__ import annotations
from contextvars import ContextVar
import re
from decimal import ROUND_HALF_UP, Decimal
from html import escape
import streamlit as st
from dashboard import note_data as nd
from dashboard.i18n import STRINGS
from dashboard.note_charts import bars_vs_guidance, line_series, paired_bars
# ── Locale details the note is written in ────────────────────────────────────
_QUARTER_PREFIX = {"en": "Q", "fr": "T", "es": "T", "de": "Q"}
_THOUSANDS = {"en": ",", "fr": " ", "es": ".", "de": "."}
_DECIMAL = {"en": ".", "fr": ",", "es": ",", "de": ","}
# French and Spanish set a space before the percent sign; English and German do not.
_PCT_SPACE = {"en": "", "fr": " ", "es": " ", "de": " "}
_MONTHS_LONG = {
"en": ("January", "February", "March", "April", "May", "June", "July",
"August", "September", "October", "November", "December"),
"fr": ("janvier", "février", "mars", "avril", "mai", "juin", "juillet",
"août", "septembre", "octobre", "novembre", "décembre"),
"es": ("enero", "febrero", "marzo", "abril", "mayo", "junio", "julio",
"agosto", "septiembre", "octubre", "noviembre", "diciembre"),
"de": ("Januar", "Februar", "März", "April", "Mai", "Juni", "Juli",
"August", "September", "Oktober", "November", "Dezember"),
}
_MONTHS_SHORT = {
"en": ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"),
"fr": ("janv.", "févr.", "mars", "avr.", "mai", "juin", "juil.", "août",
"sept.", "oct.", "nov.", "déc."),
"es": ("ene.", "feb.", "mar.", "abr.", "may.", "jun.", "jul.", "ago.",
"sept.", "oct.", "nov.", "dic."),
"de": ("Jan.", "Feb.", "März", "Apr.", "Mai", "Juni", "Juli", "Aug.",
"Sept.", "Okt.", "Nov.", "Dez."),
}
# SourcedFact.source -> the tag text printed in the .src chip.
_SOURCE_TAG = {
"metrics": "note_tag_metrics",
"transcript": "note_tag_transcript",
"news": "note_tag_news",
"analyst": "note_tag_analyst",
}
_REL_CLASS = {"HIGH": "hi", "MEDIUM": "med", "LOW": "low"}
EM_DASH = "—"
NO_VALUE = "—"
# The language of the document being built. Numbers and words have to agree:
# a note that prints "96,2" under a heading that says "Revenue" is two
# documents. build() binds this once and every label resolves through it, so
# the caller's `lang` governs the whole page rather than half of it. A
# ContextVar rather than a module global because a hosted Space serves several
# sessions from one process.
_ACTIVE_LANG: ContextVar[str | None] = ContextVar("note_lang", default=None)
def _lang() -> str:
bound = _ACTIVE_LANG.get()
if bound:
return bound
try:
return st.session_state.get("ui_lang", "en")
except Exception:
return "en"
def _t(key: str, lang: str | None = None) -> str:
"""``i18n.t`` bound to this document's language rather than the session's.
*lang* overrides the bound language. It exists for the formatting helpers,
which take a language argument: without it they would format the number in
the language asked for and fetch its unit in the session's, printing
"96,2 bn$".
"""
bucket = STRINGS.get(key, {})
return bucket.get(lang or _lang()) or bucket.get("en") or key
# ── Text ─────────────────────────────────────────────────────────────────────
def _esc(text: object) -> str:
"""Escape for HTML and neutralise ``$``.
st.markdown reads a pair of dollar signs as LaTeX, which is how dollar
amounts in a brief used to render as broken maths. Every figure in this
note is a dollar amount, so this is not optional.
"""
return escape(str(text if text is not None else "")).replace("$", "$")
def _round(value: float, places: int) -> Decimal:
"""Round half up, the way a printed table does.
Binary floating point rounds 13.25 down to 13.2; a reader comparing the
note against the filing expects 13.3. Formatting a financial document is
exactly where that difference is visible.
"""
quantum = Decimal(1).scaleb(-places)
return Decimal(str(value)).quantize(quantum, rounding=ROUND_HALF_UP)
def _num(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
"""A number in the document's locale: grouped thousands, local decimal."""
if value is None:
return NO_VALUE
lang = lang or _lang()
text = f"{_round(value, places):,.{places}f}"
return (
text.replace(",", "\x00")
.replace(".", _DECIMAL[lang])
.replace("\x00", _THOUSANDS[lang])
)
def _signed(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
if value is None:
return NO_VALUE
return ("+" if value >= 0 else "-") + _num(abs(value), places, lang=lang)
def _pct(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
if value is None:
return NO_VALUE
lang = lang or _lang()
return f"{_num(value, places, lang=lang)}{_PCT_SPACE[lang]}%"
def _signed_pct(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
if value is None:
return NO_VALUE
lang = lang or _lang()
return f"{_signed(value, places, lang=lang)}{_PCT_SPACE[lang]}%"
def _bn(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
"""A currency amount in billions, bare: no unit and no symbol.
For table cells, whose column header states the unit once.
"""
return NO_VALUE if value is None else _num(value / 1e9, places, lang=lang)
def _money(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
"""A billions amount with its unit, in the document's own convention.
French, Spanish and German put the amount first and the currency last
("96,2 Md$"); English puts the symbol first and the scale straight after
the number ("$96.2bn"). Returns markup rather than text -- the dollar
sign arrives already encoded -- so callers must not escape the result.
"""
lang = lang or _lang()
amount = _bn(value, places, lang=lang)
if amount == NO_VALUE:
return NO_VALUE
unit = escape(_t("note_unit_bn", lang))
return f"${amount}{unit}" if lang == "en" else f"{amount} {unit}$"
def _unit(lang: str | None = None) -> str:
"""The billions-of-dollars unit alone, as markup.
The note prints the tile value bare and puts the unit at the head of
the subtitle ("96,2" over "Md$ · +106 % a/a"). That anatomy is kept in
every language; only the unit's own spelling changes, because English
writes the symbol first.
"""
lang = lang or _lang()
unit = escape(_t("note_unit_bn", lang))
return f"${unit}" if lang == "en" else f"{unit}$"
def _signed_money(value: float | None, places: int = 1, *, lang: str | None = None) -> str:
"""A signed billions amount with its unit, e.g. "+$5.2bn"."""
lang = lang or _lang()
if value is None:
return NO_VALUE
sign = "+" if value >= 0 else "-"
return f"{sign}{_money(abs(value), places, lang=lang)}"
def _per_share(value: float | None, *, lang: str | None = None) -> str:
"""A per-share amount, with the symbol where the language puts it."""
lang = lang or _lang()
if value is None:
return NO_VALUE
amount = _num(value, 2, lang=lang)
return f"${amount}" if lang == "en" else f"{amount} $"
def _plain(label: str) -> str:
"""A row label stripped of its unit parenthetical, for use in a sentence.
Table labels carry "(bn$)" because the column has to state the unit
once. Inline, beside an amount that states its own unit, it reads twice.
"""
return re.sub(r"\s*\([^)]*\)\s*$", "", label)
def _period_label(row: dict | None, *, lang: str | None = None, short: bool = True) -> str:
"""``Q2FY2027`` in the document's language: ``T2 FY27`` in French."""
if not row or not row.get("fq"):
return NO_VALUE
lang = lang or _lang()
year = row["fy"] % 100 if short else row["fy"]
return f"{_QUARTER_PREFIX[lang]}{row['fq']} FY{year:02d}"
def _date(value: object, *, lang: str | None = None, long: bool = False) -> str:
"""``2026-08-26`` as ``26 août 2026`` (or ``26 sept. 2026`` when short)."""
text = str(value or "")[:10]
if len(text) != 10 or text[4] != "-":
return text or NO_VALUE
lang = lang or _lang()
try:
year, month, day = int(text[:4]), int(text[5:7]), int(text[8:10])
except ValueError:
return text
names = _MONTHS_LONG[lang] if long else _MONTHS_SHORT[lang]
name = names[month - 1]
if lang == "en":
return f"{name} {day}, {year}"
return f"{day} {name} {year}"
# ── Source chips ─────────────────────────────────────────────────────────────
def _tag_text(source: object, latest: dict | None, *, lang: str | None = None) -> str:
"""The tag half of a source chip, period-qualified where that is knowable."""
key = str(source or "").strip()
if key in ("10-K", "10-Q"):
if key == "10-Q" and latest:
return f"10-Q {_period_label(latest, lang=lang)}"
if key == "10-K" and latest:
return f"10-K FY{latest['fy'] % 100:02d}"
return key
if key == "transcript" and latest:
return f"{_t('note_tag_transcript')} {_period_label(latest, lang=lang)}"
return _t(_SOURCE_TAG.get(key, "note_tag_metrics")) if key else _t("note_tag_calc")
def _src(source: object, reliability: object, latest: dict | None = None) -> str:
"""One ``.src`` chip: source tag welded to its reliability badge."""
rel = str(reliability or "MEDIUM").upper()
cls = _REL_CLASS.get(rel, "med")
return (
f'{_esc(_tag_text(source, latest))}'
f'{_esc(rel)}'
)
def _calc_src(reliability: str = "MEDIUM") -> str:
"""The chip for a number this note computed rather than read."""
cls = _REL_CLASS.get(reliability, "med")
return (
f'{_esc(_t("note_tag_calc"))}'
f'{_esc(reliability)}'
)
def _fact_src(fact: dict, latest: dict | None) -> str:
return _src(fact.get("source"), fact.get("reliability"), latest)
def _dimension(key: object) -> str:
"""A schema enum as prose. Falls back to the key with its gaps opened up."""
raw = str(key or "").strip()
if not raw:
return ""
label = _t(f"note_dim_{raw}")
if label != f"note_dim_{raw}":
return label
return raw.replace("_", " ").capitalize()
def _verdict(key: object) -> str:
raw = str(key or "").strip().lower()
if not raw:
return ""
label = _t(f"note_verdict_{raw}")
return raw if label == f"note_verdict_{raw}" else label
def _facts(brief: dict, key: str) -> list[dict]:
"""Verified-or-unmarked facts for *key*, failures dropped."""
out = []
for item in brief.get(key) or []:
if isinstance(item, dict) and str(item.get("text") or "").strip():
if str(item.get("verification_status") or "").upper() != "FAILED":
out.append(item)
return out
# ── Small markup helpers ─────────────────────────────────────────────────────
def _section(anchor: str, eyebrow: str, heading: str, body: str) -> str:
return (
f'
{_esc(eyebrow)}
'
f"
{_esc(heading)}
{body}"
)
def _empty(ticker: str) -> str:
return f'
'
def _table(headers: list[str], rows: list[list[str]], *, classes: str = "fin compact") -> str:
"""A ``table.fin``. Cells are pre-escaped by their callers on purpose:
several carry a source chip, which must reach the page as markup."""
if not rows:
return ""
head = "".join(f"
"
def _tile(key: str, value: str, sub: str, *, tone: str = "") -> str:
"""One tile. All three parts are markup, not text: they carry currency
symbols already encoded by _money/_unit/_per_share, and escaping them
again here would print the entity instead of the sign. Call sites
escape whatever they take from the brief."""
cls = f"v {tone}".strip()
return (
f'
{key}
'
f'
{value}
{sub}
'
)
# ── The masthead and the head ────────────────────────────────────────────────
def _masthead(brief: dict, latest: dict | None, lang: str) -> str:
generated = _date(brief.get("generated_at") or brief.get("data_as_of"), lang=lang, long=True)
corpus = _date(brief.get("filing_date"), lang=lang, long=True)
form = (latest or {}).get("form_type") or "10-Q"
period = _period_label(latest, lang=lang)
corpus_line = (
f'{_esc(_t("note_corpus_stop"))} {_esc(corpus)} '
f"({_esc(form)}{'' if period == NO_VALUE else ' ' + _esc(period)})"
)
return (
''
f'
"
)
def _in_brief(brief: dict, latest: dict | None) -> str:
"""``what_changed`` as the note's five-line summary, each line sourced."""
facts = _facts(brief, "what_changed")[:5]
if not facts:
return ""
items = "".join(
f"
{_esc(fact['text'])} {_fact_src(fact, latest)}
" for fact in facts
)
return (
f'
{_esc(_t("note_inbrief"))}
{items}
'
)
def _tiles(brief: dict, series: list[dict], latest: dict | None, lang: str) -> str:
"""Exactly six tiles. The grid is six columns wide; a missing measure
prints an em dash rather than collapsing the row."""
unit = _t("note_unit_bn")
prior = nd.prior_quarter(series, latest) if latest else None
ago = nd.year_ago(series, latest) if latest else None
if not latest:
return (
'
'
+ "".join(_tile(_esc(_t(k)), NO_VALUE, "") for k in (
"note_tile_revenue", "note_tile_guidance", "note_tile_gm",
"note_tile_eps", "note_tile_fcf", "note_tile_debt"))
+ "
"
)
# 1 — revenue, with both growth rates underneath
yoy = nd.growth(latest, ago)
qoq = nd.growth(latest, prior)
sub_parts = [_unit(lang)]
if yoy is not None:
sub_parts.append(f'{_signed_pct(yoy, 0, lang=lang)} {_t("note_yoy")}')
if qoq is not None:
sub_parts.append(f'{_signed_pct(qoq, 0, lang=lang)} {_t("note_qoq")}')
tiles = [_tile(_esc(_t("note_tile_revenue")), _bn(latest.get("revenue"), lang=lang),
" · ".join(sub_parts))]
# 2 — the gap to the guidance midpoint the company itself gave
beat = nd.guidance_beat(latest)
if beat:
gap, gap_pct = beat
key = (f'{_esc(_t("note_tile_guidance"))} '
f'{_money(latest["guidance_midpoint"], 0, lang=lang)}')
sub = _signed_money(gap, lang=lang)
consensus = _consensus_gap(brief, latest)
if consensus is not None:
sub += f' · {_t("note_vs_consensus")} {_signed_pct(consensus, lang=lang)}'
tiles.append(_tile(key, _signed_pct(gap_pct, lang=lang), sub,
tone="pos" if gap >= 0 else "warn"))
else:
tiles.append(_tile(_esc(_t("note_tile_guidance")), NO_VALUE, ""))
# 3 — gross margin against the margin that was guided
gm = latest.get("gross_margin")
gm_sub = []
guided_gm = latest.get("guidance_gross_margin_low")
if guided_gm is not None:
gm_sub.append(f'{_t("note_guided")} {_pct(float(guided_gm) * 100, lang=lang)}')
if latest.get("operating_margin") is not None:
gm_sub.append(f'{_t("note_op_margin_ab")} {_pct(float(latest["operating_margin"]) * 100, lang=lang)}')
tiles.append(_tile(_esc(_t("note_tile_gm")),
_pct(float(gm) * 100, lang=lang) if gm is not None else NO_VALUE,
" · ".join(gm_sub)))
# 4 — EPS
eps = latest.get("eps")
eps_sub = []
if prior and prior.get("eps") is not None:
eps_sub.append(f'{_period_label(prior, lang=lang)} {_per_share(prior["eps"], lang=lang)}')
if ago and ago.get("eps") is not None:
eps_sub.append(f'{_period_label(ago, lang=lang)} {_per_share(ago["eps"], lang=lang)}')
tiles.append(_tile(_esc(_t("note_tile_eps")), _per_share(eps, lang=lang),
" · ".join(eps_sub)))
# 5 — cash conversion, the note's quality ratio
conversion = nd.cash_conversion(latest)
fcf = nd.free_cash_flow(latest)
conv_sub = []
if fcf is not None:
conv_sub.append(f"FCF {_money(fcf, lang=lang)}")
if latest.get("net_income") is not None:
conv_sub.append(f'{_t("note_net_income_ab")} {_money(latest["net_income"], lang=lang)}')
tiles.append(_tile(_esc(_t("note_tile_fcf")),
_pct(conversion * 100, 0, lang=lang) if conversion is not None else NO_VALUE,
" · ".join(conv_sub),
tone="warn" if conversion is not None and conversion < 0.6 else ""))
# 6 — debt, flagged when it moved sharply in one quarter
debt = latest.get("total_debt")
debt_delta = nd.growth(latest, prior, "total_debt")
debt_sub = [_unit(lang)]
if prior and prior.get("total_debt") is not None and debt is not None:
debt_sub.append(f'{_signed((float(debt) - float(prior["total_debt"])) / 1e9, lang=lang)} {_esc(_t("note_qoq"))}')
tiles.append(_tile(_esc(_t("note_tile_debt")), _bn(debt, lang=lang), " · ".join(debt_sub),
tone="warn" if debt_delta is not None and debt_delta > 25 else ""))
return '
' + "".join(tiles) + "
"
def _consensus_gap(brief: dict, latest: dict) -> float | None:
"""Revenue against consensus, but only when the tool vouched for the match.
``comparison_allowed`` is the gate the pipeline sets after checking that
the estimate covers the period actually reported. Without it a consensus
number is a different quarter's expectation and comparing them invents a
beat or a miss.
"""
me = brief.get("market_expectations") or {}
if not isinstance(me, dict) or me.get("comparison_allowed") is not True:
return None
estimate = me.get("consensus_rev_est_bn")
revenue = latest.get("revenue")
if estimate in (None, 0) or revenue is None:
return None
try:
return (float(revenue) / 1e9 - float(estimate)) / float(estimate) * 100.0
except (TypeError, ValueError, ZeroDivisionError):
return None
# ── Contents ─────────────────────────────────────────────────────────────────
_TOC = (
("resume", "note_toc_resume"),
("print", "note_toc_print"),
("cash", "note_toc_cash"),
("bilan", "note_toc_balance"),
("segments", "note_toc_mix"),
("direction", "note_toc_mgmt"),
("capital", "note_toc_capital"),
("bullbear", "note_toc_debate"),
("watch", "note_toc_watch"),
("annexes", "note_toc_annex"),
)
def _toc() -> str:
links = "".join(f'{_esc(_t(key))}' for anchor, key in _TOC)
return f''
# ── Figures ──────────────────────────────────────────────────────────────────
def _figure(svg: str, caption: str) -> str:
"""One ````: the chart inline, then its caption.
Inline rather than an data URI so the chart keeps reading the page's
CSS variables and its own ``.ct``/``.cv``/``.cb`` class rules, exactly as
the published note's figures do. See note_charts._svg for the one
attribute Streamlit requires that the published note does without.
"""
return f"{svg}{caption}" if svg else ""
# ── Section 1 — what matters ─────────────────────────────────────────────────
def _readings(brief: dict, latest: dict | None) -> list[str]:
"""The numbered readings: the between-the-lines items first, then the
earnings-quality signals, then the takeaway. Each keeps its source."""
out: list[str] = []
for item in brief.get("between_the_lines") or []:
if not isinstance(item, dict):
continue
observation = str(item.get("observation") or "").strip()
reading = str(item.get("reading") or "").strip()
implication = str(item.get("implication") or "").strip()
if not (observation or reading):
continue
evidence = item.get("evidence") if isinstance(item.get("evidence"), dict) else {}
body = f"{_esc(observation)} {_esc(reading)}"
if implication:
body += f" {_esc(implication)}"
out.append(body + _src(evidence.get("source"), evidence.get("reliability") or "MEDIUM", latest))
for signal in brief.get("earnings_quality_signals") or []:
if not isinstance(signal, dict):
continue
dimension = _dimension(signal.get("dimension"))
rationale = str(signal.get("rationale") or "").strip()
assessment = _verdict(signal.get("assessment"))
if not (dimension or rationale):
continue
evidence = signal.get("evidence") if isinstance(signal.get("evidence"), dict) else {}
label = f"{dimension} {EM_DASH} {assessment}" if assessment else dimension
out.append(
f"{_esc(label)} {_esc(rationale)}"
+ _src(evidence.get("source"), evidence.get("reliability") or "MEDIUM", latest)
)
takeaway = str(brief.get("non_obvious_takeaway") or "").strip()
if takeaway and takeaway != _lede(brief):
out.append(_esc(takeaway) + _calc_src("MEDIUM"))
return out
def _gap_flag(brief: dict) -> str:
"""The note's own statement of what it could not read.
Printed even when there is nothing missing: a reader who has learnt to
look here for the caveats should find an explicit all-clear, not silence
that could equally mean the check was skipped.
"""
gaps: list[str] = []
coverage = brief.get("coverage") or {}
if isinstance(coverage, dict):
for gap in coverage.get("gaps") or []:
text = str(gap or "").strip()
if text:
gaps.append(text)
for name, block in coverage.items():
if not isinstance(block, dict):
continue
if str(block.get("status") or "").upper() in ("MISSING", "EMPTY", "FAILED"):
gaps.append(f'{name}: {_t("note_aside_absent")}')
for note in brief.get("evidence_notes") or []:
text = str(note or "").strip()
if text:
gaps.append(text)
if not gaps:
body = _esc(_t("note_gap_none"))
else:
body = (
f'{_esc(_t("note_gap_title"))} '
+ " ".join(_esc(g if g.endswith(".") else g + ".") for g in gaps[:4])
+ " "
+ _esc(_t("note_gap_flagged"))
)
return f'
{body}
'
def _section_resume(brief: dict, latest: dict | None, ticker: str) -> str:
thesis = str(brief.get("what_matters_most") or "").strip()
readings = _readings(brief, latest)
body = ""
if thesis:
body += f'
{_esc(thesis)}
'
if readings:
body += "" + "".join(f"
{item}
" for item in readings) + ""
if not body:
body = _empty(ticker)
return _section(
"resume", _t("note_eb_resume"),
_t("note_h2_resume").format(n=len(readings) or ""),
body + _gap_flag(brief),
)
# ── Section 2 — the quarter against guidance, consensus and history ──────────
def _section_print(brief: dict, series: list[dict], latest: dict | None, ticker: str, lang: str) -> str:
if not latest:
return _section("print", _t("note_eb_print"), _t("note_h2_print"), _empty(ticker))
unit = _t("note_unit_bn")
prior = nd.prior_quarter(series, latest)
ago = nd.year_ago(series, latest)
me = brief.get("market_expectations") or {}
consensus_allowed = isinstance(me, dict) and me.get("comparison_allowed") is True
def cell(row: dict | None, fn) -> str:
return NO_VALUE if not row else fn(row)
band = latest.get("guidance_band")
guided_revenue = NO_VALUE
if band:
mid = (band[0] + band[1]) / 2
spread = (band[1] - band[0]) / 2 / mid * 100 if mid else None
guided_revenue = _bn(mid, lang=lang)
if spread:
guided_revenue += f" ± {_pct(spread, 0, lang=lang)}"
gm_guided = latest.get("guidance_gross_margin_low")
rows = [
[_esc(_t("note_row_revenue").format(u=unit)),
_bn(latest.get("revenue"), lang=lang), guided_revenue,
_num(me.get("consensus_rev_est_bn"), lang=lang) if consensus_allowed else NO_VALUE,
cell(prior, lambda r: _bn(r.get("revenue"), lang=lang)),
cell(ago, lambda r: _bn(r.get("revenue"), lang=lang))],
[_esc(_t("note_row_gm")),
_pct(float(latest["gross_margin"]) * 100, lang=lang) if latest.get("gross_margin") is not None else NO_VALUE,
_pct(float(gm_guided) * 100, lang=lang) if gm_guided is not None else NO_VALUE,
NO_VALUE,
cell(prior, lambda r: _pct(float(r["gross_margin"]) * 100, lang=lang) if r.get("gross_margin") is not None else NO_VALUE),
cell(ago, lambda r: _pct(float(r["gross_margin"]) * 100, lang=lang) if r.get("gross_margin") is not None else NO_VALUE)],
[_esc(_t("note_row_opex").format(u=unit)),
_bn(nd.opex(latest), 2, lang=lang), NO_VALUE, NO_VALUE,
cell(prior, lambda r: _bn(nd.opex(r), 2, lang=lang)),
cell(ago, lambda r: _bn(nd.opex(r), 2, lang=lang))],
[_esc(_t("note_row_op_margin")),
_pct(float(latest["operating_margin"]) * 100, lang=lang) if latest.get("operating_margin") is not None else NO_VALUE,
NO_VALUE, NO_VALUE,
cell(prior, lambda r: _pct(float(r["operating_margin"]) * 100, lang=lang) if r.get("operating_margin") is not None else NO_VALUE),
cell(ago, lambda r: _pct(float(r["operating_margin"]) * 100, lang=lang) if r.get("operating_margin") is not None else NO_VALUE)],
[_esc(_t("note_row_tax")),
_pct(float(latest["effective_tax_rate"]) * 100, lang=lang) if latest.get("effective_tax_rate") is not None else NO_VALUE,
NO_VALUE, NO_VALUE,
cell(prior, lambda r: _pct(float(r["effective_tax_rate"]) * 100, lang=lang) if r.get("effective_tax_rate") is not None else NO_VALUE),
cell(ago, lambda r: _pct(float(r["effective_tax_rate"]) * 100, lang=lang) if r.get("effective_tax_rate") is not None else NO_VALUE)],
[_esc(_t("note_row_eps")),
_num(latest.get("eps"), 2, lang=lang), NO_VALUE,
_num(me.get("consensus_eps_est"), 2, lang=lang) if consensus_allowed else NO_VALUE,
cell(prior, lambda r: _num(r.get("eps"), 2, lang=lang)),
cell(ago, lambda r: _num(r.get("eps"), 2, lang=lang))],
[_esc(_t("note_row_fcf").format(u=unit)),
_bn(nd.free_cash_flow(latest), lang=lang), NO_VALUE, NO_VALUE,
cell(prior, lambda r: _bn(nd.free_cash_flow(r), lang=lang)),
cell(ago, lambda r: _bn(nd.free_cash_flow(r), lang=lang))],
[_esc(_t("note_row_returns").format(u=unit)),
_bn(nd.shareholder_returns(latest), lang=lang), NO_VALUE, NO_VALUE,
cell(prior, lambda r: _bn(nd.shareholder_returns(r), lang=lang)),
cell(ago, lambda r: _bn(nd.shareholder_returns(r), lang=lang))],
]
headers = [
_esc(_period_label(latest, lang=lang)),
_esc(_t("note_th_published")),
_esc(_t("note_th_guidance")),
_esc(_t("note_th_consensus")),
_esc(_period_label(prior, lang=lang)),
_esc(_period_label(ago, lang=lang)),
]
body = _table(headers, rows)
body += (
'
"
# Net income against free cash flow, quarter by quarter.
groups = []
for row in series[-9:]:
net_income, quarter_fcf = row.get("net_income"), nd.free_cash_flow(row)
if net_income is None or quarter_fcf is None:
continue
ratio = nd.cash_conversion(row)
groups.append({
"label": _period_label(row, lang=lang),
"left": float(net_income) / 1e9,
"left_text": _num(float(net_income) / 1e9, 1, lang=lang),
"right": quarter_fcf / 1e9,
"right_text": _num(quarter_fcf / 1e9, 1, lang=lang),
"ratio": _pct(ratio * 100, 0, lang=lang) if ratio is not None else "",
"ratio_warn": ratio is not None and ratio < 0.6,
})
if groups:
svg = paired_bars(
groups,
label=_t("note_fig_cash_caption"),
footnote=f'{unit}$ · {_t("note_fig_cash_legend")}',
)
body += _figure(
svg,
_esc(_t("note_fig_cash_caption"))
+ _src("metrics", "HIGH", latest) + _calc_src("MEDIUM"),
)
# Days sales outstanding — where a receivable-funded quarter shows up.
points = []
for row in series[-9:]:
days = nd.dso(row)
if days is None:
continue
points.append({
"label": _period_label(row, lang=lang),
"value": days,
"value_text": _num(days, 0, lang=lang),
"emphasis": row is latest,
})
if points:
svg = line_series(
points,
label=_t("note_fig_dso_caption"),
footnote=f'{_t("note_row_dso")} · {_t("note_fig_dso_legend")}',
)
body += _figure(
svg,
_esc(_t("note_fig_dso_caption")) + _calc_src("MEDIUM"),
)
body += _bridge_table(series, latest, lang, unit)
signals = [
s for s in brief.get("earnings_quality_signals") or []
if isinstance(s, dict) and str(s.get("rationale") or "").strip()
]
if signals:
for signal in signals[:3]:
evidence = signal.get("evidence") if isinstance(signal.get("evidence"), dict) else {}
snippet = str(evidence.get("evidence_snippet") or "").strip()
if not snippet:
continue
body += (
f'
{_esc(snippet)}
'
f'
{_esc(signal.get("rationale"))}
'
)
return _section("cash", _t("note_eb_cash"), _t("note_h2_cash"), body or _empty(ticker))
def _bridge_table(series: list[dict], latest: dict, lang: str, unit: str) -> str:
"""Net income to operating cash flow, with the unexplained gap named.
The residual line is the point of the table. Everything the corpus tags
is listed; whatever the tagged items do not account for is shown as a
residual rather than folded silently into another line.
"""
ocf = latest.get("operating_cash_flow")
net_income = latest.get("net_income")
if ocf is None or net_income is None:
return ""
prior = nd.prior_quarter(series, latest)
def delta(key: str) -> float | None:
if not prior or latest.get(key) is None or prior.get(key) is None:
return None
return float(latest[key]) - float(prior[key])
rows: list[list[str]] = [[_esc(_t("note_row_net_income")), _bn(net_income, lang=lang)]]
accounted = float(net_income)
for key, label, sign in (
("depreciation_amortization", "note_row_da", +1),
("sbc", "note_row_sbc", +1),
):
value = latest.get(key)
if value is None:
continue
accounted += sign * float(value)
rows.append([_esc(_t(label)), _signed(sign * float(value) / 1e9, lang=lang)])
for key, label in (
("receivables", "note_row_receivables"),
("inventory", "note_row_inventory"),
("deferred_revenue", "note_row_deferred"),
):
change = delta(key)
if change is None:
continue
# A receivable or an inventory build consumes cash; deferred revenue supplies it.
effect = change if key == "deferred_revenue" else -change
accounted += effect
rows.append([_esc(_t(label)), _signed(effect / 1e9, lang=lang)])
residual = float(ocf) - accounted
rows.append([_esc(_t("note_row_residual")), _signed(residual / 1e9, lang=lang)])
rows.append([_esc(_t("note_row_ocf")), _bn(ocf, lang=lang)])
table = _table([_esc(_t("note_th_line")), f"{_esc(unit)}$"], rows)
return f'
{_esc(_t("note_h3_ni_to_ocf"))}
{table}'
# ── Section 4 — the balance sheet ────────────────────────────────────────────
def _section_balance(brief: dict, series: list[dict], latest: dict | None, ticker: str, lang: str) -> str:
if not latest:
return _section("bilan", _t("note_eb_balance"), _t("note_h2_balance"), _empty(ticker))
unit = _t("note_unit_bn")
prior = nd.prior_quarter(series, latest)
lines: list[str] = []
rows: list[list[str]] = []
for key, label in (
("receivables", "note_row_receivables"),
("inventory", "note_row_inventory"),
("deferred_revenue", "note_row_deferred"),
("total_debt", "note_row_debt"),
("cash_and_st_investments", "note_row_cash"),
("stockholders_equity", "note_row_equity"),
):
now = latest.get(key)
if now is None:
continue
then = (prior or {}).get(key)
change = None if then is None else float(now) - float(then)
rows.append([
_esc(_t(label)),
_bn(now, lang=lang),
NO_VALUE if then is None else _bn(then, lang=lang),
NO_VALUE if change is None else _signed(change / 1e9, lang=lang),
])
# Risks the filing itself marks as new are the note's "what is new" line.
for risk in brief.get("risks_categorized") or []:
if not isinstance(risk, dict) or not risk.get("is_new_this_filing"):
continue
text = str(risk.get("text") or "").strip()
if text:
lines.append(
f'
{_esc(risk.get("category") or "")} {_esc(text)}'
+ _fact_src(risk, latest) + "
"
)
body = ""
if lines:
body += f'
{_esc(_t("note_h3_balance_delta"))}
{"".join(lines)}
'
if rows:
headers = [
_esc(_t("note_th_metric")),
_esc(_period_label(latest, lang=lang)),
_esc(_period_label(prior, lang=lang)),
_esc(_t("note_th_gap")),
]
body += _table(headers, rows)
body += (
f'
'
)
return _section("bilan", _t("note_eb_balance"), _t("note_h2_balance"), body or _empty(ticker))
# ── Section 5 — revenue mix ──────────────────────────────────────────────────
def _section_mix(brief: dict, latest: dict | None, ticker: str, lang: str) -> str:
rows: list[list[str]] = []
note = ""
try:
from storage import segments_db
for axis in ("srt:ProductOrServiceAxis", "us-gaap:StatementBusinessSegmentsAxis"):
period_end = segments_db.latest_period_end(ticker, axis)
if not period_end:
continue
members = segments_db.read_segments(ticker, axis, period_end)
total = sum(float(m["revenue"]) for m in members if m.get("revenue")) or 0.0
for member in members:
revenue = member.get("revenue")
if revenue is None:
continue
label = str(member.get("label") or member.get("member") or "").split(":")[-1]
label = label.removesuffix("Member")
rows.append([
_esc(label),
_bn(revenue, lang=lang),
_pct(float(revenue) / total * 100, lang=lang) if total else NO_VALUE,
_esc(_date(period_end, lang=lang)),
])
if rows:
# The mix can lag the income statement by a quarter: segment
# tables are tagged on their own schedule. Say which period is
# on screen rather than letting it read as the latest one.
if latest and str(period_end) != str(latest.get("report_date")):
note = (
f'
'
)
break
except Exception:
rows = []
body = note
if rows:
headers = [
_esc(_t("note_th_segment")),
f'{_esc(_t("note_unit_bn"))}$',
_esc(_t("note_th_share")),
_esc(_t("note_th_quarter")),
]
body += _table(headers, rows)
for driver in (brief.get("mda_summary") or {}).get("drivers") or []:
if isinstance(driver, dict) and str(driver.get("text") or "").strip():
body += f'
{_esc(driver["text"])}{_fact_src(driver, latest)}
'
return _section("segments", _t("note_eb_mix"), _t("note_h2_mix"), body or _empty(ticker))
# ── Section 6 — management on the record ─────────────────────────────────────
def _section_management(brief: dict, latest: dict | None, ticker: str) -> str:
body = ""
mda = brief.get("mda_summary") or {}
key_quote = mda.get("key_quote") if isinstance(mda, dict) else None
if isinstance(key_quote, dict) and str(key_quote.get("evidence_snippet") or "").strip():
body += (
f'
{_esc(key_quote["evidence_snippet"])}
'
f'
{_esc(key_quote.get("text") or "")}
'
)
for topic in brief.get("management_commentary") or []:
if not isinstance(topic, dict):
continue
summary = str(topic.get("summary") or "").strip()
if not summary:
continue
heading = str(topic.get("topic") or "").strip()
body += (
(f"
{_esc(heading)}
" if heading else "")
+ f"
{_esc(summary)}{_fact_src(topic, latest)}
"
)
for headwind in (mda.get("headwinds") or []) if isinstance(mda, dict) else []:
if isinstance(headwind, dict) and str(headwind.get("text") or "").strip():
body += (
f'
"
)
return _section("direction", _t("note_eb_mgmt"), _t("note_h2_mgmt"), body or _empty(ticker))
# ── Section 7 — capital allocation ───────────────────────────────────────────
def _section_capital(series: list[dict], latest: dict | None, ticker: str, lang: str) -> str:
if not latest:
return _section("capital", _t("note_eb_capital"), _t("note_h2_capital"), _empty(ticker))
unit = _t("note_unit_bn")
prior = nd.prior_quarter(series, latest)
items: list[str] = []
for key, label in (
("buybacks", "note_row_buybacks"),
("dividends_paid", "note_row_dividends"),
):
value = latest.get(key)
if value is None:
continue
line = f'{_esc(_plain(_t(label)))} {_money(value, lang=lang)}'
then = (prior or {}).get(key)
if then is not None:
line += (
f' ({_esc(_period_label(prior, lang=lang))}: '
f'{_money(then, lang=lang)})'
)
items.append(f'
{line}{_src("10-Q", "HIGH", latest)}
')
returns, fcf = nd.shareholder_returns(latest), nd.free_cash_flow(latest)
if returns is not None and fcf:
items.append(
f'
"
)
shares = latest.get("shares_diluted")
if shares is not None:
line = (f'{_esc(_t("note_row_shares"))} '
f'{_bn(shares, 2, lang=lang)} {_esc(_t("note_unit_bn"))}')
change = nd.growth(latest, prior, "shares_diluted")
if change is not None:
line += f' · {_signed_pct(change, lang=lang)} {_esc(_t("note_qoq"))}'
items.append(f'
{line}{_src("metrics", "HIGH", latest)}
')
debt = latest.get("total_debt")
if debt is not None:
line = f'{_esc(_t("note_row_debt"))} {_money(debt, lang=lang)}'
then = (prior or {}).get("total_debt")
if then is not None:
line += (
f' ({_esc(_period_label(prior, lang=lang))}: '
f'{_money(then, lang=lang)})'
)
items.append(f'
{line}{_src("10-Q", "HIGH", latest)}
')
body = f'
{"".join(items)}
' if items else _empty(ticker)
return _section("capital", _t("note_eb_capital"), _t("note_h2_capital"), body)
# ── Section 8 — the two readings ─────────────────────────────────────────────
def _section_debate(brief: dict, latest: dict | None, ticker: str) -> str:
bull = _facts(brief, "bull_points")
bear = _facts(brief, "bear_points")
if not bull and not bear:
return _section("bullbear", _t("note_eb_debate"), _t("note_h2_debate"), _empty(ticker))
def column(heading: str, facts: list[dict]) -> str:
if not facts:
return f"
"
)
return _section("bullbear", _t("note_eb_debate"), _t("note_h2_debate"), body)
# ── Section 9 — the calendar ─────────────────────────────────────────────────
def _section_watch(brief: dict, latest: dict | None, ticker: str) -> str:
items = []
watch = brief.get("what_to_watch") or []
for entry in watch:
if isinstance(entry, dict):
text = str(entry.get("text") or entry.get("watch") or "").strip()
when = str(entry.get("event_date") or entry.get("period") or "").strip()
else:
text = str(entry or "").strip()
when = ""
if not text:
continue
# No date in the data means no date on the page. The column still needs
# a value, so it says what kind of horizon this is instead of guessing.
when = when or (
_t("note_watch_next_read")
if any(word in text.lower() for word in ("next quarter", "next filing", "10-q", "transcript",
"prochain", "próximo", "nächst"))
else _t("note_watch_ongoing")
)
items.append(
f'
"
)
def _section_annexes(brief: dict, series: list[dict], latest: dict | None,
market: dict | None, ticker: str, lang: str) -> str:
unit = _t("note_unit_bn")
body = ""
# The guidance record: every quarter the company guided, against what it filed.
track_rows = []
for row in series:
beat = nd.guidance_beat(row)
if not beat:
continue
gap, gap_pct = beat
gm_guided = row.get("guidance_gross_margin_low")
track_rows.append([
_esc(_period_label(row, lang=lang)) + ("d" if row.get("derived") else ""),
_bn(row["guidance_midpoint"], lang=lang),
_bn(row.get("revenue"), lang=lang),
_signed_pct(gap_pct, lang=lang),
_signed(gap / 1e9, lang=lang),
_pct(float(gm_guided) * 100, lang=lang) if gm_guided is not None else NO_VALUE,
_pct(float(row["gross_margin"]) * 100, lang=lang) if row.get("gross_margin") is not None else NO_VALUE,
])
if track_rows:
headers = [
_esc(_t("note_th_quarter")),
f'{_esc(_t("note_th_guidance"))} ({_esc(_t("note_th_midpoint"))})',
_esc(_t("note_th_actual")),
_esc(_t("note_th_gap")),
f'{_esc(_t("note_th_gap"))} ({_esc(unit)}$)',
f'{_esc(_t("note_tile_gm"))} {_esc(_t("note_guided"))}',
_esc(_t("note_th_actual")),
]
footnote = (
'
d '
+ _esc(_t("note_method_derived").format(mark="d"))
+ "
"
)
body += _annexe(
_t("note_annex_eb_history"), _t("note_h3_track"),
_table(headers, track_rows) + footnote,
)
# Multiples, printed as market context and nothing more.
if market:
rows = []
for key, label in (
("price", "note_aside_price"),
("trailing_pe", None),
("forward_pe", None),
("ev_to_sales", None),
("ev_to_ebitda", None),
("dividend_yield_pct", None),
):
value = market.get(key)
if value is None:
continue
name = _t(label) if label else key.replace("_", " ").upper()
text = (
_pct(float(value), 2, lang=lang) if key == "dividend_yield_pct"
else _num(float(value), 2, lang=lang)
)
rows.append([_esc(name), text])
if rows:
body += _annexe(
_t("note_annex_eb_market"), _t("note_h3_multiples"),
_table([_esc(_t("note_th_metric")), _esc(_t("note_th_value"))], rows)
+ f'
'
)
if market:
pairs = []
if market.get("price") is not None:
pairs.append((_esc(_t("note_aside_price")), _per_share(market["price"], lang=lang)))
if market.get("market_cap"):
pairs.append((_esc(_t("note_aside_mcap")),
_money(market["market_cap"], 0, lang=lang)))
if market.get("week52_low") and market.get("week52_high"):
pairs.append((
_esc(_t("note_aside_52w")),
f'{_per_share(market["week52_low"], lang=lang)}{EM_DASH}'
f'{_per_share(market["week52_high"], lang=lang)}',
))
if pairs:
boxes.append(
f'
{_esc(_t("note_aside_market"))}
{_dl(pairs)}'
f'
{_esc(_t("note_aside_market_note"))}
'
)
coverage = brief.get("coverage") or {}
pairs = [(_esc(_t("note_aside_quarters")), _esc(str(len(series))))]
if isinstance(coverage, dict):
for name, label in (
("filings", "note_aside_filings"),
("transcripts", "note_aside_transcripts"),
("news", "note_aside_news"),
):
block = coverage.get(name)
if isinstance(block, dict):
count = block.get("evidence_count")
pairs.append((
_esc(_t(label)),
_esc(str(count) if count is not None else (block.get("status") or NO_VALUE)),
))
report = brief.get("evidence_coverage") or brief.get("verification_report") or {}
if isinstance(report, dict) and report.get("verified") is not None:
total = report.get("total") or (
(report.get("verified") or 0) + (report.get("unverified") or 0) + (report.get("failed") or 0)
)
pairs.append((_esc(_t("note_aside_verified")), _esc(f'{report["verified"]} / {total}')))
boxes.append(f'
{_esc(_t("note_aside_coverage"))}
{_dl(pairs)}
')
boxes.append(
f'
{_esc(_t("note_aside_rel"))}
'
f'
HIGH{_esc(_t("note_rel_hi"))}
'
f'
MEDIUM{_esc(_t("note_rel_med"))}
'
f'
LOW{_esc(_t("note_rel_low"))}
'
"
"
)
return ""
# ── The footer ───────────────────────────────────────────────────────────────
def _footer(brief: dict, series: list[dict], latest: dict | None, lang: str) -> str:
sources = []
seen: set[str] = set()
for row in reversed(series):
accession = str(row.get("accession") or "")
if not accession or accession in seen or row.get("derived"):
continue
seen.add(accession)
form = row.get("form_type") or "10-Q"
label = (
f'{form} {_period_label(row, lang=lang, short=False)}, {_t("note_aside_accession")} '
f'{accession}, {_t("note_aside_filed")} {_date(row.get("filing_date"), lang=lang)}'
)
url = row.get("source_url")
item = _esc(label)
if url:
item += f' {EM_DASH} sec.gov'
sources.append(f"
{item}
")
if len(sources) >= 6:
break
method = "".join(
f"
{_esc(text)}
"
for text in (
_t("note_method_corpus"),
_t("note_method_derived").format(mark="d"),
_t("note_method_fcf"),
_t("note_method_verified"),
)
)
return (
'"
)
# ── Assembly ─────────────────────────────────────────────────────────────────
def build(brief: dict, *, series: list[dict] | None = None,
market: dict | None = None, lang: str | None = None) -> str:
"""Return the note as one HTML string. No Streamlit, no network."""
token = _ACTIVE_LANG.set(lang or _lang())
try:
return _build(brief, series=series, market=market)
finally:
_ACTIVE_LANG.reset(token)
def _build(brief: dict, *, series: list[dict] | None, market: dict | None) -> str:
lang = _lang()
ticker = str((brief or {}).get("ticker") or "")
series = series if series is not None else nd.quarter_series(ticker)
latest = series[-1] if series else None
main = (
""
+ _section_resume(brief, latest, ticker)
+ _section_print(brief, series, latest, ticker, lang)
+ _section_cash(brief, series, latest, ticker, lang)
+ _section_balance(brief, series, latest, ticker, lang)
+ _section_mix(brief, latest, ticker, lang)
+ _section_management(brief, latest, ticker)
+ _section_capital(series, latest, ticker, lang)
+ _section_debate(brief, latest, ticker)
+ _section_watch(brief, latest, ticker)
+ _section_annexes(brief, series, latest, market, ticker, lang)
+ ""
)
return (
'
"
)
def _market(ticker: str) -> dict | None:
"""Cached quote and multiples, or None. Never raises, never blocks a render."""
try:
from analytics.valuation import fetch_multiples
data, _error = fetch_multiples(ticker)
return data or None
except Exception:
return None
def render(brief: dict) -> None:
"""The Brief, as the note. Streamlit entry point.
The stylesheet is not injected here: ``theme.inject_global_css`` ships it
once per page load, pinned to the light tokens. Re-injecting the
dark-capable ``TOKENS`` from inside a rerun would let the document flip
palette while the plotly charts on the other routes could not follow.
``st.markdown`` rather than ``st.html``: st.html's sanitiser strips
``