alphacouncil-agent 0.5.0

package/mcp/lib/markets.mjs

@@ -0,0 +1,261 @@
+import { LIMITS } from "./constants.mjs";
+import { invalidParams } from "./errors.mjs";
+import { fetchQuote } from "./quotes.mjs";
+import { fetchDartFinancials, fetchEdinetFilings } from "./markets-kr-jp.mjs";
+
+/**
+ * Where structured financials come from, per market, and what to do when they do not.
+ *
+ * The pipeline was US-only in everything but name: an industry map could list SK hynix
+ * and Kioxia, and then nothing could fetch a number for them. This declares the real
+ * capability of each market and degrades in a stated order rather than silently
+ * producing a US-only answer dressed as a global one.
+ *
+ * Tiers, in the order they are tried:
+ *   1. keyless regulator feed  -- SEC (US), TWSE (TW)
+ *   2. regulator feed needing a free key -- DART (KR), EDINET (JP); reported as
+ *      not_configured rather than pretended away
+ *   3. quotes, which work everywhere, plus search -- always labelled as such, because a
+ *      price is not a financial statement
+ */
+
+export const MARKETS = {
+  US: {
+    id: "US",
+    suffixes: [""],
+    regulator: "SEC EDGAR",
+    tier: "keyless",
+    capability: "full",
+    note: "companyfacts XBRL: full statements with filing dates.",
+  },
+  TW: {
+    id: "TW",
+    suffixes: [".TW", ".TWO"],
+    regulator: "TWSE OpenAPI",
+    tier: "keyless",
+    capability: "summary",
+    note: "quarterly income-statement summary for listed companies; no full XBRL history.",
+  },
+  KR: {
+    id: "KR",
+    suffixes: [".KS", ".KQ"],
+    regulator: "DART (opendart.fss.or.kr)",
+    tier: "free_key",
+    env: "ALPHACOUNCIL_DART_KEY",
+    capability: "full",
+    note: "full filings, but requires a free API key. Register at opendart.fss.or.kr.",
+  },
+  JP: {
+    id: "JP",
+    suffixes: [".T"],
+    regulator: "EDINET v2 (api.edinet-fsa.go.jp)",
+    tier: "free_key",
+    env: "ALPHACOUNCIL_EDINET_KEY",
+    capability: "full",
+    note: "full filings, but requires a free subscription key from the EDINET portal.",
+  },
+  HK: {
+    id: "HK",
+    suffixes: [".HK"],
+    regulator: "HKEXnews",
+    tier: "none",
+    capability: "documents_only",
+    note: "no machine-readable financial API; filings are PDFs. Use search plus WebFetch on hkexnews.hk.",
+  },
+  CN: {
+    id: "CN",
+    suffixes: [".SS", ".SZ"],
+    regulator: "cninfo / 巨潮资讯",
+    tier: "none",
+    capability: "documents_only",
+    note: "no stable public API; filings are PDFs. Use search plus WebFetch on cninfo.com.cn.",
+  },
+};
+
+export function marketFor(symbol) {
+  const text = String(symbol || "").trim().toUpperCase();
+  if (!text) return null;
+  for (const market of Object.values(MARKETS)) {
+    if (market.id === "US") continue;
+    if (market.suffixes.some((s) => s && text.endsWith(s))) return market;
+  }
+  // No recognised suffix means a plain US ticker.
+  return /^[A-Z0-9.\-]{1,10}$/.test(text) ? MARKETS.US : null;
+}
+
+/** Is a market's primary feed actually usable right now? */
+export function feedStatus(market) {
+  if (!market) return { available: false, reason: "unrecognised market" };
+  if (market.tier === "keyless") return { available: true, tier: "keyless" };
+  if (market.tier === "free_key") {
+    const configured = Boolean(process.env[market.env]);
+    return {
+      available: configured,
+      tier: "free_key",
+      env: market.env,
+      reason: configured ? undefined : `${market.regulator} needs ${market.env}; ${market.note}`,
+    };
+  }
+  return { available: false, tier: "none", reason: market.note };
+}
+
+// ---- Taiwan: the one non-US feed that needs no key -------------------------
+
+let twseCache = null;
+let twseCachedAt = 0;
+const TWSE_TTL_MS = 6 * 60 * 60 * 1000;
+
+async function twseIncomeStatements() {
+  if (twseCache && Date.now() - twseCachedAt < TWSE_TTL_MS) return twseCache;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), LIMITS.QUOTE_FETCH_MS * 2);
+  try {
+    const res = await fetch("https://openapi.twse.com.tw/v1/opendata/t187ap06_L_ci", {
+      signal: ctrl.signal,
+      headers: { Accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    twseCache = await res.json();
+    twseCachedAt = Date.now();
+    return twseCache;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Read a TWSE field by name, returning null when the field is absent.
+ *
+ * TWSE uses full-width parentheses -- 營業毛利（毛損）, not 營業毛利(毛損). Getting that
+ * wrong made gross profit and operating income read as 0 for every Taiwanese company:
+ * a wrong number that looks like a real one, which is worse than a gap.
+ */
+const twField = (row, key) => {
+  if (!(key in row)) throw new Error(`TWSE field "${key}" is not in the dataset; the schema changed`);
+  const raw = String(row[key] ?? "").trim();
+  if (!raw) return null;
+  const n = Number(raw.replace(/,/g, ""));
+  return Number.isFinite(n) ? n : null;
+};
+
+/** Latest reported quarter for a Taiwan listed company, in TWD thousands as filed. */
+export async function fetchTaiwanFinancials(symbol) {
+  const code = String(symbol).toUpperCase().replace(/\.(TW|TWO)$/, "");
+  const rows = await twseIncomeStatements();
+  const match = rows.filter((r) => String(r["公司代號"]) === code);
+  if (!match.length) return null;
+  const row = match[match.length - 1];
+  return {
+    market: "TW",
+    source: "TWSE OpenAPI",
+    company_code: code,
+    company_name: row["公司名稱"],
+    period: { year: row["年度"], quarter: row["季別"] },
+    reported_at: row["出表日期"],
+    currency: "TWD",
+    unit: "thousands as filed",
+    // TWSE reports the ROC calendar; 115 is 2026.
+    calendar: "ROC",
+    gregorian_year: Number(row["年度"]) + 1911,
+    revenue: twField(row, "營業收入"),
+    cost_of_revenue: twField(row, "營業成本"),
+    gross_profit: twField(row, "營業毛利（毛損）"),
+    operating_expenses: twField(row, "營業費用"),
+    operating_income: twField(row, "營業利益（損失）"),
+    pretax_income: twField(row, "稅前淨利（淨損）"),
+    net_income: twField(row, "本期淨利（淨損）"),
+    eps: twField(row, "基本每股盈餘（元）"),
+    note: "Quarterly summary only. TWSE publishes no full XBRL history, so multi-year rules cannot be computed from this source.",
+  };
+}
+
+/**
+ * Structured financials for any market, degrading in a stated order.
+ *
+ * Never returns an empty result silently: when the primary feed is unavailable it says
+ * which feed, why, and what the caller should do instead.
+ */
+export async function fetchMarketFinancials(symbol, extra = {}) {
+  const market = marketFor(symbol);
+  if (!market) throw invalidParams(`cannot identify a market for symbol "${symbol}"`);
+  const status = feedStatus(market);
+
+  const base = {
+    symbol,
+    market: market.id,
+    regulator: market.regulator,
+    feed: status,
+  };
+
+  if (market.id === "US") {
+    return {
+      ...base,
+      financials: null,
+      guidance: "US filer: use list_us_universe to resolve the CIK, then screen_ticker or compose_research_brief for full XBRL history.",
+    };
+  }
+
+  if (market.id === "TW" && status.available) {
+    const financials = await fetchTaiwanFinancials(symbol).catch(() => null);
+    if (financials) return { ...base, financials, guidance: financials.note };
+    return { ...base, financials: null, guidance: `Not found in the TWSE dataset for ${symbol}. Fall back to the quote and to search.` };
+  }
+
+  if (market.id === "KR" && status.available) {
+    const kr = await fetchDartFinancials({ corpCode: extra.corp_code, year: extra.year || new Date().getFullYear() - 1 })
+      .catch((e) => ({ available: false, reason: String(e?.message || e) }));
+    if (kr.available) return { ...base, financials: kr, guidance: kr.note };
+    return { ...base, financials: null, guidance: kr.reason };
+  }
+
+  if (market.id === "JP" && status.available) {
+    const jp = await fetchEdinetFilings({ secCode: symbol }).catch((e) => ({ available: false, reason: String(e?.message || e) }));
+    if (jp.available) return { ...base, financials: null, filings: jp.filings, guidance: jp.note };
+    return { ...base, financials: null, guidance: jp.reason };
+  }
+
+  // Everything else: say what is missing and fall back to what always works.
+  const quote = await fetchQuote(symbol).catch((e) => ({ error: String(e?.message || e) }));
+  return {
+    ...base,
+    financials: null,
+    fallback: {
+      quote: quote && !quote.error ? quote : null,
+      quote_error: quote?.error,
+      // A price is not a financial statement and the report must not treat it as one.
+      caveat: "A quote is market data, not a financial statement. Any statement about margins, "
+        + "cash flow or leverage for this name has to come from search over primary documents, "
+        + "and must be cited as such.",
+    },
+    guidance: status.available
+      ? `No structured adapter for ${market.regulator} yet. Use search plus WebFetch on the regulator's site.`
+      : `${status.reason} Until then, use search plus WebFetch on the regulator's site and label the figures as sourced from documents rather than a structured feed.`,
+  };
+}
+
+/** What the pipeline can and cannot do for a set of symbols. Answers it up front. */
+export function coverageFor(symbols = []) {
+  const rows = symbols.map((symbol) => {
+    const market = marketFor(symbol);
+    const status = market ? feedStatus(market) : { available: false, reason: "unrecognised" };
+    return {
+      symbol,
+      market: market?.id ?? "unknown",
+      regulator: market?.regulator ?? "-",
+      structured_financials: status.available ? (market.capability === "summary" ? "summary only" : "yes") : "no",
+      reason: status.reason,
+      needs_env: market?.env && !status.available ? market.env : undefined,
+    };
+  });
+  return {
+    rows,
+    summary: {
+      full: rows.filter((r) => r.structured_financials === "yes").length,
+      summary_only: rows.filter((r) => r.structured_financials === "summary only").length,
+      none: rows.filter((r) => r.structured_financials === "no").length,
+    },
+    note: "Names without structured financials are not excluded from research -- they are researched from "
+      + "documents and search, and every figure taken that way must be labelled as such so a reader can tell "
+      + "which numbers came from a filing feed and which came from a document someone read.",
+  };
+}

package/mcp/lib/narrative.mjs

@@ -0,0 +1,235 @@
+import { fetchFeeds, MARKET_FEEDS, queryNewsFeed } from "./feeds.mjs";
+import { getMacroSnapshot } from "./macro.mjs";
+
+/**
+ * What story is the market currently telling itself, and does the tape agree?
+ *
+ * The pipeline could already read a company's filings and the macro tape, but not the
+ * thing that actually moves crowded positioning: the prevailing narrative. That gap
+ * matters because a name is repriced by the story it gets attached to long before its
+ * fundamentals change.
+ *
+ * The design rule is the separation: **headlines are what people are saying, the macro
+ * series is what happened.** Both are reported, never merged. When a theme dominates the
+ * press and the corresponding series has not moved, that divergence is the finding -- it
+ * is either a story running ahead of the data or a market that has stopped listening.
+ *
+ * Honest limitation, stated in the output: this can only find themes in its lexicon. It
+ * will not discover an unnamed theme, and it says so rather than implying full coverage.
+ */
+
+/**
+ * Each theme carries the terms that identify it and the series that would corroborate it.
+ * `check` refers to a macro block member label or derived-measure id from macro.mjs, so a
+ * claim about rates is answered by the actual 10-year rather than by more headlines.
+ */
+export const THEMES = [
+  {
+    id: "rates_policy",
+    label: { zh: "利率与货币政策", en: "Rates and monetary policy" },
+    terms: ["rate cut", "rate hike", "interest rate", "federal reserve", "fed ", "fomc", "powell",
+      "monetary policy", "basis point", "tightening", "easing", "quantitative"],
+    check: { series: ["US 10Y", "US 3M"], derived: ["spread_10y_3m"] },
+  },
+  {
+    id: "treasury_yields",
+    label: { zh: "美债收益率与财政", en: "Treasury yields and fiscal" },
+    terms: ["treasury yield", "bond market", "10-year", "30-year", "debt ceiling", "deficit",
+      "bond selloff", "auction", "fiscal", "sovereign debt"],
+    check: { series: ["US 10Y", "US 30Y"], derived: ["spread_10y_3m"] },
+  },
+  {
+    id: "inflation",
+    label: { zh: "通胀", en: "Inflation" },
+    terms: ["inflation", "cpi", "ppi", "price pressure", "disinflation", "core pce", "cost of living"],
+    check: { series: ["Gold", "Crude"], derived: [] },
+  },
+  {
+    id: "ai_capex",
+    label: { zh: "AI 与资本开支周期", en: "AI and the capex cycle" },
+    terms: ["artificial intelligence", " ai ", "data center", "datacenter", "capex", "capital expenditure",
+      "hyperscaler", "gpu", "accelerator", "compute", "model training", "inference"],
+    check: { series: ["Nasdaq 100", "Semiconductors"], derived: [] },
+  },
+  {
+    id: "geopolitics",
+    label: { zh: "地缘政治与能源", en: "Geopolitics and energy" },
+    terms: ["iran", "israel", "ukraine", "russia", "strait", "middle east", "military strike",
+      "sanction", "war", "conflict", "opec", "oil supply"],
+    check: { series: ["Crude", "Gold"], derived: [] },
+  },
+  {
+    id: "trade_tariffs",
+    label: { zh: "关税与贸易", en: "Tariffs and trade" },
+    terms: ["tariff", "trade war", "export control", "import duty", "trade deal", "supply chain",
+      "decoupling", "entity list", "chip export"],
+    check: { series: ["Dollar index"], derived: [] },
+  },
+  {
+    id: "credit_stress",
+    label: { zh: "信用与流动性压力", en: "Credit and liquidity stress" },
+    terms: ["credit spread", "default", "bankruptcy", "refinancing risk", "refinancing wall",
+      "high yield", "distressed", "bank failure", "liquidity crunch", "credit downgrade",
+      "debt maturity", "covenant"],
+    check: { series: ["High yield", "Investment grade", "VIX"], derived: ["hyg_lqd"] },
+  },
+  {
+    id: "growth_recession",
+    label: { zh: "增长与衰退", en: "Growth and recession" },
+    terms: ["recession", "slowdown", "soft landing", "hard landing", "gdp", "unemployment",
+      "jobless", "payroll", "layoff", "consumer spending"],
+    check: { series: ["Copper", "Gold"], derived: ["copper_gold"] },
+  },
+  {
+    id: "dollar_fx",
+    label: { zh: "美元与汇率", en: "Dollar and currencies" },
+    terms: ["dollar index", "currency", "yen", "euro", "devalu", "forex", "exchange rate", "peg"],
+    check: { series: ["Dollar index"], derived: [] },
+  },
+  {
+    id: "china",
+    label: { zh: "中国", en: "China" },
+    terms: ["china", "beijing", "yuan", "renminbi", "property developer", "stimulus", "pboc"],
+    check: { series: ["China A", "Hong Kong"], derived: [] },
+  },
+  {
+    id: "earnings_season",
+    label: { zh: "财报季", en: "Earnings season" },
+    terms: ["earnings", "guidance", "beat estimates", "missed estimates", "quarterly results",
+      "profit margin", "revenue growth", "outlook cut", "outlook raise"],
+    check: { series: ["S&P 500"], derived: [] },
+  },
+  {
+    id: "politics_policy",
+    label: { zh: "政治与监管", en: "Politics and regulation" },
+    terms: ["election", "white house", "congress", "regulation", "antitrust", "executive order",
+      "shutdown", "legislation", "president"],
+    check: { series: [], derived: [] },
+  },
+];
+
+const normalize = (s) => ` ${String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim()} `;
+
+/**
+ * Match a term at a word boundary.
+ *
+ * Long terms match as a prefix so "tariff" catches "tariffs" and "refinanc" catches
+ * "refinancing". Short ones must be whole words, because a prefix rule on "ai" would fire
+ * on "aid" and "aircraft" and quietly inflate the AI theme -- the kind of error that makes
+ * a coverage share look authoritative while being wrong.
+ */
+const hasTerm = (text, term) => {
+  const t = normalize(term).trim();
+  if (!t) return false;
+  return t.length <= 3 ? text.includes(` ${t} `) : text.includes(` ${t}`);
+};
+
+/** Which themes does one headline touch? A headline may carry more than one. */
+export function classify(title) {
+  const text = normalize(title);
+  const hits = [];
+  for (const theme of THEMES) {
+    const matched = theme.terms.filter((term) => hasTerm(text, term));
+    if (matched.length) hits.push({ id: theme.id, matched });
+  }
+  return hits;
+}
+
+/** Pull the corroborating numbers for a theme out of an already-fetched macro snapshot. */
+function marketCheck(theme, macro) {
+  if (!macro) return { available: false, reason: "macro snapshot unavailable" };
+  const series = [];
+  for (const block of macro.blocks || []) {
+    for (const member of block.members || []) {
+      if (theme.check.series.includes(member.label)) {
+        const q = member.quote || {};
+        series.push({
+          label: member.label,
+          symbol: member.symbol,
+          value: q.price ?? null,
+          change_pct: q.change_pct ?? null,
+          quote_time: q.quote_time ?? null,
+          available: q.price != null,
+        });
+      }
+    }
+  }
+  const derived = (macro.derived || [])
+    .filter((d) => theme.check.derived.includes(d.id))
+    .map((d) => ({ id: d.id, label: d.label, value: d.value ?? null, available: Boolean(d.available) }));
+  if (!series.length && !derived.length) {
+    return { available: false, reason: "no series in this snapshot corroborates this theme" };
+  }
+  return { available: true, series, derived };
+}
+
+export async function getMarketNarrative({ days = 7, asOf = null, extra_queries = [], top = 6 } = {}) {
+  const specs = [
+    ...MARKET_FEEDS,
+    ...(Array.isArray(extra_queries) ? extra_queries.slice(0, 4).map((q) => queryNewsFeed(q)) : []),
+  ];
+  // The narrative and the tape are fetched independently on purpose; neither informs the other.
+  const [news, macro] = await Promise.all([
+    fetchFeeds(specs, { days, asOf }),
+    getMacroSnapshot({}).catch(() => null),
+  ]);
+
+  const counts = new Map(THEMES.map((t) => [t.id, []]));
+  let unclassified = 0;
+  for (const item of news.items) {
+    const hits = classify(item.title);
+    if (!hits.length) { unclassified += 1; continue; }
+    for (const hit of hits) counts.get(hit.id).push({ ...item, matched: hit.matched });
+  }
+
+  const total = news.items.length || 1;
+  const themes = THEMES
+    .map((theme) => {
+      const items = counts.get(theme.id);
+      const check = marketCheck(theme, macro);
+      return {
+        id: theme.id,
+        label: theme.label,
+        headline_count: items.length,
+        share_of_coverage_pct: Number(((items.length / total) * 100).toFixed(1)),
+        market_check: check,
+        // Sample headlines carry their timestamp and link so any claim can be reopened.
+        sample: items.slice(0, 4).map((i) => ({
+          title: i.title, source: i.source, published_at: i.published_at, link: i.link, matched: i.matched,
+        })),
+      };
+    })
+    .filter((t) => t.headline_count > 0)
+    .sort((a, b) => b.headline_count - a.headline_count)
+    .slice(0, top);
+
+  return {
+    as_of: asOf || new Date().toISOString().slice(0, 10),
+    window_days: days,
+    headlines_in_window: news.items.length,
+    excluded_outside_window: news.excluded_outside_window,
+    excluded_sample: news.excluded_sample,
+    feeds: news.feeds,
+    unreachable: news.unreachable,
+    themes,
+    unclassified_headlines: unclassified,
+    interpretation_rules: [
+      "Headline counts measure what is being said, not what is true. A theme leading coverage "
+      + "is evidence about attention and positioning, never about the underlying fact.",
+      "Where a theme dominates coverage and its market_check series has not moved, that gap is "
+      + "the finding: either the story is ahead of the data, or the market has stopped listening. "
+      + "Say which you think it is and why.",
+      "Never let a theme's prominence change a conclusion on a single name by itself. It sets "
+      + "the environment the name is being priced in; it is not evidence about the business.",
+    ],
+    coverage_limits: [
+      `Themes are matched against a fixed lexicon of ${THEMES.length} entries, so a genuinely new `
+      + "narrative will land in unclassified_headlines rather than being discovered. "
+      + `${unclassified} headlines in this window matched nothing.`,
+      "English-language feeds only. A theme leading the Asian or European press and absent here "
+      + "is a blind spot of this tool, not an absence of the theme.",
+      "No social media. Positioning talk that lives on X or in group chats is not visible to "
+      + "this layer, and a crowded trade can be crowded without appearing in any headline.",
+    ],
+  };
+}