"""ModelEvidenceClaim: every model-derived claim knows its source model, and every piece of evidence ABOUT a model knows which models it may evaluate. Visibility follows the source model's reliability, per model: an UNRELIABLE cross-sectional rank contributes no token at all (not a token plus an instruction not to use it), whatever the single-stock price model's state is. A reliability statistic of model A can describe model A only; it never evaluates model B unless B is listed in ``applicable_target_model_ids``. """ from __future__ import annotations FUNDAMENTAL_FORECAST = "FUNDAMENTAL_FORECAST" SINGLE_STOCK_PRICE_MODEL = "SINGLE_STOCK_PRICE_MODEL" CROSS_SECTIONAL_PANEL_RANK = "CROSS_SECTIONAL_PANEL_RANK" ANALYST_PANEL = "ANALYST_PANEL" STORY_VALUATION = "STORY_VALUATION" MECHANICAL_DCF = "MECHANICAL_DCF" MARKET_PRICING = "MARKET_PRICING" MODELS = (FUNDAMENTAL_FORECAST, SINGLE_STOCK_PRICE_MODEL, CROSS_SECTIONAL_PANEL_RANK, ANALYST_PANEL, STORY_VALUATION, MECHANICAL_DCF, MARKET_PRICING) FAMILY = {FUNDAMENTAL_FORECAST: "reconciled fundamental forecast", SINGLE_STOCK_PRICE_MODEL: "machine learning (single stock)", CROSS_SECTIONAL_PANEL_RANK: "machine learning (cross-sectional rank)", ANALYST_PANEL: "LLM analyst debate", STORY_VALUATION: "intrinsic valuation (story DCF)", MECHANICAL_DCF: "intrinsic valuation (mechanical DCF)", MARKET_PRICING: "market pricing (multiples and analyst targets)"} # model OUTPUT claims (what the model produced) _OUTPUTS = { FUNDAMENTAL_FORECAST: ("FORECAST_REVENUE", "FORECAST_REVENUE_GROWTH", "FORECAST_OPERATING_MARGIN", "FORECAST_NET_MARGIN", "FORECAST_OPERATING_MARGIN_CHANGE", "FORECAST_EPS", "FORECAST_EPS_GROWTH", "FORECAST_EPS_VS_CONSENSUS", "REL_FORECAST_EPS_CONSENSUS", "PE_FORWARD", "PEG"), CROSS_SECTIONAL_PANEL_RANK: ("ML_RANK_SHARE", "ML_RANK_DECILE", "ML_RANK_UNIVERSE"), STORY_VALUATION: ("INTRINSIC_VALUE", "PRICE_VS_INTRINSIC", "REL_PRICE_INTRINSIC", "STORY_TAM", "STORY_SHARE", "STORY_REVENUE_MATURITY", "STORY_YEARS", "STORY_MARGIN", "STORY_START_MARGIN", "STORY_START_REVENUE", "STORY_MARGIN_CHANGE", "STORY_WACC", "STORY_WACC_STABLE", "STORY_WACC_HOLD", "STORY_TERMINAL_GROWTH", "STORY_FAILURE", "BE_REVENUE", "BE_REVENUE_CAGR", "BE_MARGIN", "REL_BREAK_EVEN_REVENUE_STORY", "REL_BREAK_EVEN_MARGIN_STORY", "REL_BREAK_EVEN_REVENUE_GROWTH", "REL_EXPECTATIONS_STORY"), MECHANICAL_DCF: ("MECHANICAL_VALUE", "PRICE_VS_MECHANICAL", "REL_PRICE_MECHANICAL"), MARKET_PRICING: ("MARKET_COMPOSITE", "MARKET_COMPOSITE_RAW", "MARKET_COMPOSITE_POST_TRIM", "ANALYST_TARGET_ADJUSTED", "PRICE_VS_COMPOSITE", "REL_PRICE_MARKET_COMPOSITE"), ANALYST_PANEL: ("SCENARIO_BEAR_RETURN", "SCENARIO_NEUTRAL_RETURN", "SCENARIO_BULL_RETURN", "SCENARIO_BEAR_PROB", "SCENARIO_NEUTRAL_PROB", "SCENARIO_BULL_PROB", "PM_RETURN", "SCENARIO_BEAR_RETURN_PHRASE", "SCENARIO_NEUTRAL_RETURN_PHRASE", "SCENARIO_BULL_RETURN_PHRASE", "PM_RETURN_PHRASE"), } # EVIDENCE claims (statistics about a model's reliability): claim id → (source model, reliability path, metric id) _EVIDENCE = { "ML_RANK_IC": (CROSS_SECTIONAL_PANEL_RANK, "quant.panel_rank.reliability", "rank_ic"), "ML_RANK_POSITIVE": (CROSS_SECTIONAL_PANEL_RANK, "quant.panel_rank.reliability", "ic_positive_share"), } _RELIABILITY = {SINGLE_STOCK_PRICE_MODEL: "quant.price_model.reliability", CROSS_SECTIONAL_PANEL_RANK: "quant.panel_rank.reliability"} CLAIM_MODEL = {cid: m for m, ids in _OUTPUTS.items() for cid in ids} CLAIM_MODEL.update({cid: v[0] for cid, v in _EVIDENCE.items()}) CLAIM_MODEL.update({"TREND_REVENUE": FUNDAMENTAL_FORECAST, "TREND_OPERATING_MARGIN": FUNDAMENTAL_FORECAST, "TREND_EPS": FUNDAMENTAL_FORECAST}) def claim_model(cid): return CLAIM_MODEL.get(str(cid).split("__")[0]) if cid else None # ── EvidenceInterpretationClaim: what an evidence family may support in prose ────────────────────────────── DESCRIPTIVE_ONLY, DIRECTIONAL_ALLOWED = "DESCRIPTIVE_ONLY", "DIRECTIONAL_ALLOWED" # per evidence family: the claims that carry it, how a sentence names it, and the interpretive predicates a # DESCRIPTIVE_ONLY family may not carry (the family's declared interpretation surface) INTERPRETATION_FAMILIES = { "13F": {"claims": ("OWN_13F_AS_OF", "OWN_13F_HOLDERS", "OWN_13F_HOLDERS_PREV", "OWN_13F_TRACKED", "OWN_13F_NEW", "OWN_13F_ADDS", "OWN_13F_TRIMS", "OWN_13F_EXITS", "OWN_13F_NAMES", "OWN_13F_HOLDERS_CHANGE", "OWN_13F_HOLDERS_CHANGE_PHRASE"), "subjects": ("institution", "institutional", "holder", "sponsorship", "ownership", "13f", "filers", "positioning", "flows", "tracked investor", "tracked long-term", "long-term investor", "fund ", "funds", "shareholder base", "holder base", "breadth"), "permission_path": "ownership.permissions.use_as_return_signal"}, "insider": {"claims": ("INSIDER_CHARACTERIZATION", "INSIDER_DISCRETIONARY_NET", "INSIDER_MATERIALITY"), "subjects": ("insider", "form 4", "executives bought", "executives sold", "management bought", "management sold"), "permission_path": "insiders.canon.materiality.material"}, } INTERPRETIVE_SURFACE = ("pressure", "weaken", "strengthen", "fading", "fades", "fade ", "erod", "thinning", "thins", "deepening", "support", "constructive", "healthy", "unhealthy", "bearish", "bullish", "confidence", "conviction", "accumulat", "distribution", "momentum", "signal", "warning", "red flag", "tailwind", "headwind", "improving", "deteriorat", "exodus", "crowded", "floor", "cushion", "backing", "endorse", "vote of", "smart money", "flight", "abandon", "embrac", "rotation out", "rotation into", "losing interest", "gaining interest", "stable", "sticky", "reassur", "de-risk", "derisk", "validat", "confirm", "soften", "align") def interpretation(state): """{family: {permission, claims, subjects, source}}: DIRECTIONAL_ALLOWED only when the state permits the family as a return signal; otherwise DESCRIPTIVE_ONLY (positions and counts, never what they imply).""" out = {} for fam, d in INTERPRETATION_FAMILIES.items(): allowed = bool(state.value(d["permission_path"])) if hasattr(state, "value") else False out[fam] = {"family": fam, "permission": DIRECTIONAL_ALLOWED if allowed else DESCRIPTIVE_ONLY, "claims": list(d["claims"]), "subjects": list(d["subjects"]), "source": d["permission_path"]} return out def reliability(state, model_id): p = _RELIABILITY.get(model_id) return (state.get(p) or {}) if p else {} def model_visible(state, model_id): """A model's claims may be offered to an author only when its own reliability allows it (per model, never OR'd).""" if model_id not in _RELIABILITY: return True return bool(reliability(state, model_id).get("persona_visibility")) def build(state): """{claims: {evidence_id: ModelEvidenceClaim}, models: {model_id: {...}}}.""" claims = {} for cid, (mid, path, key) in _EVIDENCE.items(): rel = state.get(path) or {} vis = model_visible(state, mid) claims[cid] = {"evidence_id": cid, "source_model_id": mid, "source_model_family": FAMILY[mid], "metric_id": key, "metric_value": rel.get(key), "reliability_status": rel.get("state"), "persona_visible": vis, "usable_as_evidence": bool(vis and rel.get("state") not in ("UNRELIABLE", "UNAVAILABLE")), "applicable_target_model_ids": [mid], "allowed_uses": [f"describe the reliability of the {FAMILY[mid]}"] if vis else []} models = {} for mid in MODELS: rel = reliability(state, mid) models[mid] = {"model_id": mid, "model_family": FAMILY[mid], "reliability_status": rel.get("state"), "persona_visible": model_visible(state, mid), "output_claims": list(_OUTPUTS.get(mid, ())), "evidence_claims": [c for c, v in _EVIDENCE.items() if v[0] == mid]} return {"claims": claims, "models": models, "interpretation": interpretation(state), "uses": evidence_uses(state), "news": news_claims(state)} def evidence_targets(state, cid): """(source model, allowed target models) for an evidence claim, or None when the claim is not evidence.""" e = ((state.get("evidence.state") or {}).get("claims") or {}).get(cid) if e is None: v = _EVIDENCE.get(cid) return (v[0], [v[0]]) if v else None return e["source_model_id"], list(e.get("applicable_target_model_ids") or []) # ── EvidenceDomain: what kind of conclusion a piece of evidence may establish ──────────────────────────────── FUNDAMENTALS, VALUATION, MOMENTUM, OWNERSHIP, INSIDERS, MACRO, GUIDANCE, QUANT = ( "FUNDAMENTALS", "VALUATION", "MOMENTUM", "OWNERSHIP", "INSIDERS", "MACRO", "GUIDANCE", "QUANT") EVIDENCE_DOMAINS = { MOMENTUM: {"claims": ("SMA200", "MOMENTUM", "RETURN_3M", "RETURN_12M", "RETURN_3M_PHRASE", "RETURN_12M_PHRASE"), "subjects": ("200-day", "200 day", "moving average", "momentum", "technical", "chart", "tape", "price trend"), "allowed_target_domains": (MOMENTUM, "TECHNICAL_SETUP")}, OWNERSHIP: {"claims": INTERPRETATION_FAMILIES["13F"]["claims"], "subjects": ("13f", "institutional", "holders"), "allowed_target_domains": (OWNERSHIP,)}, INSIDERS: {"claims": INTERPRETATION_FAMILIES["insider"]["claims"], "subjects": ("insider", "form 4"), "allowed_target_domains": (INSIDERS,)}, QUANT: {"claims": ("ML_RANK_SHARE", "ML_RANK_DECILE", "ML_RANK_UNIVERSE", "ML_RANK_IC", "ML_RANK_POSITIVE"), "subjects": ("machine-learning", "machine learning", "quant model", "price model"), "allowed_target_domains": (QUANT,)}, } # a FUNDAMENTALS conclusion is a trend in the business (the TrendRelationship surface) FUNDAMENTAL_EVIDENCE_PREFIXES = ("REVENUE_", "OPERATING_", "NET_", "EPS_", "FORECAST_", "CONSENSUS_", "LIFECYCLE_", "GUIDANCE_", "TREND_", "STORY_MARGIN_CHANGE", "BE_", "REL_BREAK_EVEN") def evidence_domain(cid): for dom, d in EVIDENCE_DOMAINS.items(): if cid in d["claims"]: return dom return None # ── ConclusionDomain: what a sentence concludes, and which evidence domains may establish it ───────────────── REVENUE_GROWTH_C, MARGIN_C, EPS_C = "REVENUE_GROWTH", "MARGIN", "EPS" CONCLUSION_SUBJECTS = {REVENUE_GROWTH_C: ("revenue", "sales", "top line", "top-line", "growth"), MARGIN_C: ("margin",), EPS_C: ("eps", "earnings", "profit", "income")} # evidence domains that may establish each fundamental conclusion CONCLUSION_EVIDENCE = {REVENUE_GROWTH_C: (FUNDAMENTALS, GUIDANCE), MARGIN_C: (FUNDAMENTALS, GUIDANCE), EPS_C: (FUNDAMENTALS, GUIDANCE)} for _d in EVIDENCE_DOMAINS.values(): _d.setdefault("source_domain", None) for _k, _d in EVIDENCE_DOMAINS.items(): _d["source_domain"] = _k def conclusion_domain(window): """The fundamental conclusion a trend word near these words is about (REVENUE_GROWTH by default).""" import re as _re for dom in (MARGIN_C, EPS_C, REVENUE_GROWTH_C): if any(_re.search(r"\b" + _re.escape(w) + r"\b", window) for w in CONCLUSION_SUBJECTS[dom]): return dom return REVENUE_GROWTH_C # ── EvidenceUse: which CONCLUSION TYPES each piece of evidence may support ─────────────────────────────────── # conclusion types a sentence can assert, each with the surface that asserts it (owned by the conclusion type) MARKET_PRESSURE, RECOVERY_OUTLOOK, MOAT_OR_SECULAR_GROWTH, STOCK_UPSIDE = ( "MARKET_PRESSURE", "RECOVERY_OUTLOOK", "MOAT_OR_SECULAR_GROWTH", "STOCK_UPSIDE") CONCLUSION_TYPES = { MARKET_PRESSURE: ("pressure", "support", "tailwind", "headwind", "confidence", "conviction", "bullish", "bearish", "accumulat", "distribution", "flows", "floor", "cushion", "backing", "endorse", "signal", "alignment", "aligned"), RECOVERY_OUTLOOK: ("transient", "temporary", "entry point", "buying opportunit", "rebound", "recover", "bounce back", "permanent impairment", "muted long-run", "short-lived"), MOAT_OR_SECULAR_GROWTH: ("moat", "secular", "embedded", "centrality", "central role", "relevance", "underscor", "reinforc", "pricing power", "switching cost", "network effect", "indispensab", "essential"), STOCK_UPSIDE: ("upside", "re-rating", "rerating", "catalyst", "undervalued", "mispriced", "room to run"), } DESCRIPTIVE_TYPES = ("POSITION_DESCRIPTION", "TRADE_DESCRIPTION", "MATERIALITY_DESCRIPTION", "NEWS_DESCRIPTION", "SYSTEMATIC_RISK_DESCRIPTION", "DISCOUNT_RATE_INPUT", "SENSITIVITY_CONTEXT", "TECHNICAL_SETUP") EVIDENCE_USE = { "BETA": {"claims": ("DMD_BETA", "DMD_UNLEVERED_BETA"), "subjects": ("beta",), "source_domain": MACRO, "allowed_target_domains": (VALUATION,), "allowed_conclusion_types": ("SYSTEMATIC_RISK_DESCRIPTION", "DISCOUNT_RATE_INPUT", "SENSITIVITY_CONTEXT")}, "RISK_PREMIUM": {"claims": ("DMD_ERP", "DMD_IMPLIED_ERP", "DMD_CRP"), "subjects": ("risk premium",), "source_domain": MACRO, "allowed_target_domains": (VALUATION,), "allowed_conclusion_types": ("DISCOUNT_RATE_INPUT", "SENSITIVITY_CONTEXT")}, "INSIDER": {"claims": INTERPRETATION_FAMILIES["insider"]["claims"], "subjects": ("insider", "form 4"), "source_domain": INSIDERS, "allowed_target_domains": (INSIDERS,), "allowed_conclusion_types": ("TRADE_DESCRIPTION", "MATERIALITY_DESCRIPTION"), "directional_family": "insider"}, "OWNERSHIP": {"claims": INTERPRETATION_FAMILIES["13F"]["claims"], "subjects": ("13f", "institutional", "tracked long-term"), "source_domain": OWNERSHIP, "allowed_target_domains": (OWNERSHIP,), "allowed_conclusion_types": ("POSITION_DESCRIPTION",), "directional_family": "13F"}, "MOMENTUM": {"claims": EVIDENCE_DOMAINS[MOMENTUM]["claims"], "subjects": EVIDENCE_DOMAINS[MOMENTUM]["subjects"], "source_domain": MOMENTUM, "allowed_target_domains": EVIDENCE_DOMAINS[MOMENTUM]["allowed_target_domains"], "allowed_conclusion_types": ("TECHNICAL_SETUP",)}, "NEWS": {"claims": (), "subjects": ("headline", "news", "press report", "rating action", "index change", "index membership"), "source_domain": "NEWS", "allowed_target_domains": ("NEWS",), "allowed_conclusion_types": ("NEWS_DESCRIPTION",)}, } def evidence_uses(state): """{use: EvidenceUse}: a directional family with DIRECTIONAL_ALLOWED permission may also support MARKET_PRESSURE.""" interp = interpretation(state) out = {} for k, u in EVIDENCE_USE.items(): allowed = list(u["allowed_conclusion_types"]) fam = u.get("directional_family") if fam and (interp.get(fam) or {}).get("permission") == DIRECTIONAL_ALLOWED: allowed.append(MARKET_PRESSURE) out[k] = {"evidence_use": k, "evidence_claim_ids": list(u["claims"]), "subjects": list(u["subjects"]), "source_domain": u["source_domain"], "allowed_target_domains": list(u["allowed_target_domains"]), "allowed_conclusion_types": allowed} return out # ── NewsEvidenceClaim: what a headline is about, and what it may be used for ───────────────────────────────── _RATING_WORDS = ("rating", "rates ", "affirm", "upgrade", "downgrade", "outlook", "credit watch", "creditwatch") _INDEX_WORDS = ("index", "added to", "join", "rebalanc", "constituent") def news_claims(state): """[NewsEvidenceClaim]. A headline that names the issuer as the rating agency or index provider acting on ANOTHER entity is about that entity: it is descriptive context, never evidence of the issuer's growth, moat or upside. No headline is directional until a relevance classification exists.""" import re as _re name = str(state.get("identity.company_name") or state.get("identity.name") or "").lower() full = _re.sub(r"\b(inc|corp|corporation|plc|ltd|limited|co|company|holdings|group)\b\.?", "", name).strip(" ,.") brand = full.split(" ")[0] if full else "" tick = str(state.get("identity.ticker") or "").lower() out = [] for i, n in enumerate(state.get("context.news") or [], 1): t = str((n or {}).get("title") or "") low = t.lower() issuer = bool(full and full in low) or bool(tick and _re.search(r"\b" + _re.escape(tick) + r"\b", low)) branded = bool(brand and len(brand) > 2 and brand in low) if (issuer or branded) and any(w in low for w in _RATING_WORDS): ev, about, rel = "RATING_ACTION_ON_OTHER_ENTITY", False, "NONE" elif (issuer or branded) and any(w in low for w in _INDEX_WORDS): ev, about, rel = "INDEX_ACTION", False, "NONE" elif issuer: ev, about, rel = "ISSUER_NEWS", True, "UNCLASSIFIED" elif branded: ev, about, rel = "BRAND_OR_INDEX_MENTION", False, "NONE" else: ev, about, rel = "OTHER_ENTITY_NEWS", False, "NONE" out.append({"evidence_id": f"NEWS_{i}", "title": t[:140], "subject_entity": "issuer" if about else "other", "event_type": ev, "directly_about_issuer": about, "fundamental_relevance": rel, "relevance_domain": None, "materiality": "UNCLASSIFIED" if about else "NONE", "directional_allowed": False, "allowed_conclusion_types": ["NEWS_DESCRIPTION"]}) return out # ── TranscriptEvidence: every call quote has a speaker, and every speaker a role ──────────────────────────── # A question an analyst asks is not something the company "acknowledges". The role comes from the transcript's own # structure: the operator introduces analysts ("… from with "), officers are the verified leadership. MANAGEMENT, ANALYST, OPERATOR, UNKNOWN_SPEAKER = "MANAGEMENT", "ANALYST", "OPERATOR", "UNKNOWN" _TURN = r"^([A-Z][A-Za-z.'\- ]{1,60}?):\s+(.*)$" _INTRO = r"(?:question|line|next)\s+(?:is\s+|comes\s+)?(?:from|of)\s+([A-Z][A-Za-z.'\-]+(?:\s+[A-Z][A-Za-z.'\-]+){0,3})\s+(?:with|of|at|from)\b" def _norm(t): import re as _re return " ".join(_re.findall(r"[a-z0-9]+", str(t or "").lower().replace("’", "'"))) def transcript_turns(state): """[{speaker, role, text}] for the call excerpt the authors saw.""" import re as _re raw = str(state.get("context.transcript_excerpt") or "") officers = {_norm(v.get("name")) for v in (state.get("leadership.roles") or {}).values() if (v or {}).get("name")} turns, analysts = [], set() for line in raw.splitlines(): m = _re.match(_TURN, line.strip()) if m: turns.append([m.group(1).strip(), m.group(2)]) elif turns: turns[-1][1] += " " + line.strip() elif line.strip(): turns.append([None, line.strip()]) # the excerpt opens mid-turn: speaker unknown for sp, text in turns: if sp and sp.lower() == "operator": analysts |= {_norm(x) for x in _re.findall(_INTRO, text)} out = [] for sp, text in turns: n = _norm(sp) role = (OPERATOR if n == "operator" else MANAGEMENT if n in officers else ANALYST if n in analysts else UNKNOWN_SPEAKER) out.append({"speaker": sp, "role": role, "text": _norm(text)}) return out def quote_speaker(turns, quote): """The turn a quotation comes from, or None when it is not in the excerpt.""" q = _norm(quote) return next((t for t in turns or () if q and q in t["text"]), None)