alphacouncil-agent 0.5.0

package/mcp/lib/industry.mjs

@@ -0,0 +1,208 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { invalidParams } from "./errors.mjs";
+import { fetchUniverse, fetchSubmissions } from "./sec.mjs";
+
+/**
+ * Industry framing.
+ *
+ * A question like "how does memory look right now" cannot be answered by a pipeline whose
+ * only entry point is a single ticker, and it cannot be answered honestly by asking a
+ * model to list the participants either -- that produces the names it saw most often,
+ * silently dropping the ones that do not file with the SEC. SK hynix and Kioxia are
+ * exactly the companies such a list loses, and in memory they are most of the industry.
+ *
+ * So the participant list is data, hand-maintained and explicitly incomplete, and the map
+ * carries the two things a model reliably gets wrong on its own: which link in the chain
+ * currently binds, and who actually creates the orders.
+ */
+const MAP_PATH = fileURLToPath(new URL("../../data/industry-map.json", import.meta.url));
+
+let cached = null;
+function load() {
+  if (!cached) cached = JSON.parse(readFileSync(MAP_PATH, "utf8"));
+  return cached;
+}
+
+export function listIndustries() {
+  const { industries } = load();
+  return Object.entries(industries).map(([id, entry]) => ({
+    id,
+    title: entry.title,
+    aliases: entry.aliases,
+    participant_count: entry.layers.reduce((n, l) => n + l.participants.length, 0),
+  }));
+}
+
+/** Resolve a free-text industry query against ids and aliases. */
+export function resolveIndustry(query) {
+  const needle = String(query || "").trim().toLowerCase();
+  if (!needle) throw invalidParams("industry query is empty");
+  const { industries } = load();
+  for (const [id, entry] of Object.entries(industries)) {
+    if (id === needle) return { id, ...entry };
+    if (entry.aliases.some((a) => a.toLowerCase() === needle)) return { id, ...entry };
+  }
+  // Fall back to substring so "存储芯片行业" or "HBM memory" still lands.
+  for (const [id, entry] of Object.entries(industries)) {
+    if (entry.aliases.some((a) => needle.includes(a.toLowerCase()) || a.toLowerCase().includes(needle))) {
+      return { id, ...entry };
+    }
+  }
+  return null;
+}
+
+/**
+ * Everything a research run needs to start on an industry rather than a ticker.
+ *
+ * Deliberately returns no verdict. It returns the frame: participants by chain position
+ * with their market and filing regime, who drives demand, the questions that must be
+ * answered, and how the industry behaves through a cycle -- because reading a cyclical's
+ * low P/E as cheap is the most expensive mistake available here.
+ */
+export function industryBrief(query) {
+  const entry = resolveIndustry(query);
+  if (!entry) {
+    const known = listIndustries().map((i) => `${i.id} (${i.aliases.slice(0, 3).join(", ")})`);
+    throw invalidParams(`no industry map for "${query}". Mapped industries: ${known.join("; ") || "none"}. Add one in data/industry-map.json.`);
+  }
+
+  const participants = entry.layers.flatMap((layer) =>
+    layer.participants.map((p) => ({ ...p, layer: layer.layer })));
+
+  // Which names this pipeline can screen mechanically, and which it cannot. Saying so up
+  // front stops a run from quietly becoming US-only.
+  const secScreenable = participants.filter((p) => p.symbol && p.market.includes("US"));
+  const needsOtherSource = participants.filter((p) => p.symbol && !p.market.includes("US"));
+  const unlisted = participants.filter((p) => !p.symbol);
+
+  return {
+    id: entry.id,
+    title: entry.title,
+    layers: entry.layers,
+    participants,
+    demand_drivers: entry.demand_drivers,
+    key_questions: entry.key_questions,
+    cyclicality: entry.cyclicality,
+    coverage: {
+      sec_screenable: secScreenable.map((p) => p.symbol),
+      needs_local_regulator_feed: needsOtherSource.map((p) => ({ symbol: p.symbol, market: p.market })),
+      unlisted: unlisted.map((p) => p.name),
+      note:
+        "screen_ticker and the SEC concepts cover US filers only. Korean, Japanese and Taiwanese participants "
+        + "have to be researched through search and their own regulators (DART, EDINET, MOPS), and unlisted "
+        + "capacity still moves global supply. Treat any conclusion drawn only from the US-listed subset as "
+        + "partial, and say so.",
+    },
+    how_to_use:
+      "This is a frame, not an answer. Run the council on the participants that matter for the question asked, "
+      + "check the demand drivers' own disclosures rather than press coverage of them, and answer the key "
+      + "questions explicitly. Guidance is not an order: distinguish what a customer said it plans to spend "
+      + "from what has actually been ordered and at what lead time.",
+  };
+}
+
+
+/**
+ * SIC industry groups. This is the half that covers EVERY industry rather than the
+ * handful someone has written a map for.
+ *
+ * SEC assigns a SIC code to every filer, so grouping by it classifies the whole US
+ * universe with no curation and no model. What it cannot give is the part a curated map
+ * exists for: chain position, non-US participants, and who actually creates the orders.
+ * So the two are used together and the brief says which half it is standing on.
+ */
+
+/** Broad SIC ranges, so a query like "banks" or "biotech" lands without an exact code. */
+export const SIC_GROUPS = [
+  { id: "agriculture", range: [100, 999], title: { zh: "农业", en: "Agriculture" } },
+  { id: "mining_energy", range: [1000, 1499], title: { zh: "采矿与能源", en: "Mining and energy" } },
+  { id: "construction", range: [1500, 1799], title: { zh: "建筑", en: "Construction" } },
+  { id: "food_beverage", range: [2000, 2199], title: { zh: "食品饮料", en: "Food and beverage" } },
+  { id: "chemicals", range: [2800, 2899], title: { zh: "化工", en: "Chemicals" } },
+  { id: "pharma_biotech", range: [2833, 2836], title: { zh: "医药与生物科技", en: "Pharma and biotech" } },
+  { id: "energy_refining", range: [2900, 2999], title: { zh: "炼化", en: "Refining" } },
+  { id: "metals", range: [3300, 3399], title: { zh: "金属", en: "Metals" } },
+  { id: "machinery", range: [3500, 3569], title: { zh: "机械", en: "Machinery" } },
+  { id: "computers_hardware", range: [3570, 3579], title: { zh: "计算机硬件", en: "Computers and hardware" } },
+  { id: "electronics", range: [3600, 3673], title: { zh: "电子", en: "Electronics" } },
+  { id: "semiconductors", range: [3674, 3674], title: { zh: "半导体", en: "Semiconductors" } },
+  { id: "instruments_medical", range: [3820, 3873], title: { zh: "仪器与医疗器械", en: "Instruments and medical devices" } },
+  { id: "transportation", range: [4000, 4799], title: { zh: "运输", en: "Transportation" } },
+  { id: "telecom", range: [4800, 4899], title: { zh: "电信", en: "Telecom" } },
+  { id: "utilities", range: [4900, 4999], title: { zh: "公用事业", en: "Utilities" } },
+  { id: "retail", range: [5200, 5999], title: { zh: "零售", en: "Retail" } },
+  { id: "banks", range: [6020, 6199], title: { zh: "银行", en: "Banks" } },
+  { id: "insurance", range: [6300, 6411], title: { zh: "保险", en: "Insurance" } },
+  { id: "real_estate", range: [6500, 6799], title: { zh: "房地产", en: "Real estate" } },
+  { id: "software", range: [7370, 7379], title: { zh: "软件与IT服务", en: "Software and IT services" } },
+  { id: "healthcare_services", range: [8000, 8099], title: { zh: "医疗服务", en: "Healthcare services" } },
+];
+
+export function sicGroupFor(sic) {
+  const code = Number(sic);
+  if (!Number.isFinite(code)) return null;
+  // Narrowest matching range wins, so 3674 is semiconductors rather than electronics.
+  const matches = SIC_GROUPS.filter((g) => code >= g.range[0] && code <= g.range[1]);
+  if (!matches.length) return null;
+  return matches.sort((a, b) => (a.range[1] - a.range[0]) - (b.range[1] - b.range[0]))[0];
+}
+
+let universeCache = null;
+
+/**
+ * Every US filer whose SIC matches a query, with no curation involved.
+ *
+ * Resolving each company's SIC needs one request per company, which is far too many for
+ * a 10k universe, so this works from a caller-supplied candidate list or from a name
+ * match. It is a starting universe, not a definitive index membership list, and says so.
+ */
+export async function peersBySic({ cik, limit = 25 } = {}) {
+  if (!cik) throw invalidParams("peersBySic needs a cik to anchor on");
+  const anchor = await fetchSubmissions(cik);
+  if (!anchor.sic) {
+    return { anchor, group: null, peers: [], note: "SEC has no SIC classification for this filer." };
+  }
+  const group = sicGroupFor(anchor.sic);
+
+  if (!universeCache) universeCache = await fetchUniverse();
+  // Company names are the only universe-wide signal available without 10k requests.
+  const words = anchor.name.toLowerCase().split(/\s+/).filter((w) => w.length > 4 && !/corp|inc|company|holdings|group|technologies/.test(w));
+  const nameMatched = words.length
+    ? universeCache.filter((c) => c.cik !== anchor.cik && words.some((w) => c.title.toLowerCase().includes(w)))
+    : [];
+
+  return {
+    anchor,
+    group: group ? { id: group.id, title: group.title, sic_range: group.range } : null,
+    sic: anchor.sic,
+    sic_description: anchor.sic_description,
+    peers: nameMatched.slice(0, limit),
+    note:
+      `SIC ${anchor.sic} (${anchor.sic_description}) classifies this filer. SIC covers every US filer, so it `
+      + "reaches industries no curated map has, but it says nothing about position in a value chain, about "
+      + "non-US participants, or about who creates the demand. Where industry_brief has a curated map, prefer it "
+      + "and use this only to widen the candidate list. Peer matching here is by company name and is a starting "
+      + "point, not an index membership list.",
+  };
+}
+
+/** Which half of the industry story is available for a query. */
+export function industryCoverage(query) {
+  const curated = resolveIndustry(query);
+  const needle = String(query || "").toLowerCase();
+  const sicGroup = SIC_GROUPS.find((g) =>
+    g.id.includes(needle) || needle.includes(g.id) || g.title.en.toLowerCase().includes(needle) || g.title.zh.includes(query));
+  return {
+    query,
+    curated: curated ? { id: curated.id, title: curated.title } : null,
+    sic_group: sicGroup ? { id: sicGroup.id, title: sicGroup.title, sic_range: sicGroup.range } : null,
+    guidance: curated
+      ? "A curated map exists: use industry_brief for the chain, the non-US participants and the demand drivers."
+      : sicGroup
+        ? "No curated map, but SIC classifies this. Use screen_ticker on candidates and research the chain and "
+          + "non-US participants through search -- and say in the report that the participant list is not curated."
+        : "Neither a curated map nor a SIC group matched. Treat the participant list as research output, state that "
+          + "it is not authoritative, and do not present it as complete.",
+  };
+}

package/mcp/lib/lang.mjs

@@ -0,0 +1,24 @@
+export function normalizeLanguage(value) {
+  const text = String(value || "").trim();
+  if (!text || /^auto|default|same|follow|跟随|默认$/i.test(text)) return "";
+  if (/^(zh|zh-cn|cn|chinese|中文|简体中文|繁体中文)$/i.test(text)) return "中文";
+  if (/^(en|en-us|english|英文)$/i.test(text)) return "English";
+  if (/^(ja|jp|ja-jp|japanese|日文|日本語)$/i.test(text)) return "日本語";
+  if (/^(ko|kr|korean|韩文|韓文|한국어)$/i.test(text)) return "한국어";
+  return text.slice(0, 40);
+}
+
+export function inferLanguage(text = "") {
+  if (/[\u3040-\u30ff]/.test(text)) return "日本語";
+  if (/[\uac00-\ud7af]/.test(text)) return "한국어";
+  if (/[\u3400-\u9fff]/.test(text)) return "中文";
+  return "English";
+}
+
+export function resolveLanguage(args = {}) {
+  return normalizeLanguage(args.language || args.output_language || args.user_language) || inferLanguage(args.prompt || args.user_prompt || "");
+}
+
+export function isChineseLanguage(language) {
+  return /中文|chinese|zh/i.test(String(language || ""));
+}

package/mcp/lib/macro.mjs

@@ -0,0 +1,167 @@
+import { fetchQuote } from "./quotes.mjs";
+import { invalidParams } from "./errors.mjs";
+
+/**
+ * Top-down macro context, built entirely from the keyless quote pipeline.
+ *
+ * Everything here is a market-priced series, so the snapshot is a set of observations
+ * rather than a forecast. No API key, no vendor account: the same Yahoo/Stooq path
+ * get_quote already uses.
+ *
+ * Deliberately NOT included: any single number claiming to say what "the regime" is.
+ * The blocks give the inputs; the macro_regime persona has to argue the reading and say
+ * what it means for the specific name under research.
+ */
+export const MACRO_BLOCKS = [
+  {
+    id: "rates",
+    title: { zh: "利率曲线", en: "Rate curve" },
+    why: {
+      zh: "曲线形状决定了折现率和银行的放贷意愿；倒挂是最被过度解读也最不该忽略的一个信号。",
+      en: "The curve sets the discount rate and the willingness of banks to lend. Inversion is the most over-read and least ignorable signal on this list.",
+    },
+    members: [
+      { symbol: "^IRX", label: "US 3M" },
+      { symbol: "^FVX", label: "US 5Y" },
+      { symbol: "^TNX", label: "US 10Y" },
+      { symbol: "^TYX", label: "US 30Y" },
+    ],
+  },
+  {
+    id: "dollar_liquidity",
+    title: { zh: "美元与流动性", en: "Dollar and liquidity" },
+    why: {
+      zh: "美元走强会同时压制非美盈利和大宗；信用利差决定弱资产负债表的公司能不能续命。",
+      en: "A stronger dollar compresses non-US earnings and commodities at once, and credit spreads decide whether weak balance sheets can refinance.",
+    },
+    members: [
+      { symbol: "DX-Y.NYB", label: "Dollar index" },
+      { symbol: "^VIX", label: "VIX" },
+      { symbol: "HYG", label: "High yield" },
+      { symbol: "LQD", label: "Investment grade" },
+    ],
+  },
+  {
+    id: "commodities",
+    title: { zh: "商品", en: "Commodities" },
+    why: {
+      zh: "铜金比是最便宜的增长代理；油价同时是成本项和通胀项。",
+      en: "The copper-gold ratio is the cheapest available growth proxy, and oil is simultaneously a cost line and an inflation input.",
+    },
+    members: [
+      { symbol: "CL=F", label: "Crude" },
+      { symbol: "GC=F", label: "Gold" },
+      { symbol: "HG=F", label: "Copper" },
+    ],
+  },
+  {
+    id: "risk_appetite",
+    title: { zh: "风险偏好与市场宽度", en: "Risk appetite and breadth" },
+    why: {
+      zh: "等权重相对市值加权的表现，揭示涨势是普遍的还是被少数权重股撑起来的。",
+      en: "Equal weight against cap weight reveals whether a rally is broad or is being carried by a handful of index heavyweights.",
+    },
+    members: [
+      { symbol: "^GSPC", label: "S&P 500" },
+      { symbol: "^NDX", label: "Nasdaq 100" },
+      { symbol: "RSP", label: "S&P equal weight" },
+      { symbol: "SPY", label: "S&P cap weight" },
+      { symbol: "^SOX", label: "Semiconductors" },
+    ],
+  },
+  {
+    id: "cross_market",
+    title: { zh: "跨市场", en: "Cross market" },
+    why: {
+      zh: "非美市场常常先于美股反映同一个宏观变化，尤其对出口链和供应链敏感的标的。",
+      en: "Non-US markets often price the same macro change first, especially for export and supply-chain exposed names.",
+    },
+    members: [
+      { symbol: "^N225", label: "Japan" },
+      { symbol: "^HSI", label: "Hong Kong" },
+      { symbol: "000001.SS", label: "China A" },
+      { symbol: "^KS11", label: "Korea" },
+      { symbol: "^TWII", label: "Taiwan" },
+    ],
+  },
+];
+
+const price = (quotes, symbol) => {
+  const quote = quotes.get(symbol);
+  return quote && !quote.error && Number.isFinite(quote.price) ? quote.price : null;
+};
+
+/**
+ * Ratios and spreads that are only meaningful as a pair. Each returns null rather than a
+ * guess when either leg is unavailable, so a data gap stays visible as a data gap.
+ */
+function derived(quotes) {
+  const out = [];
+  const push = (id, label, value, note) => out.push({ id, label, value, available: value !== null, note });
+
+  const y3m = price(quotes, "^IRX");
+  const y10 = price(quotes, "^TNX");
+  const y5 = price(quotes, "^FVX");
+  const y30 = price(quotes, "^TYX");
+
+  push("spread_10y_3m", { en: "10Y minus 3M", zh: "10年期减3个月" }, y10 !== null && y3m !== null ? Number((y10 - y3m).toFixed(3)) : null,
+    "Negative is an inverted curve. The most-watched recession proxy, and the one most often read too early.");
+  push("spread_30y_5y", { en: "30Y minus 5Y", zh: "30年期减5年期" }, y30 !== null && y5 !== null ? Number((y30 - y5).toFixed(3)) : null,
+    "Steepening at the long end usually prices term premium or inflation risk rather than growth.");
+
+  const copper = price(quotes, "HG=F");
+  const gold = price(quotes, "GC=F");
+  push("copper_gold", { en: "Copper / gold", zh: "铜金比" }, copper !== null && gold !== null ? Number((copper / gold).toFixed(6)) : null,
+    "Rising is a growth signal, falling is a flight to safety. A cheap real-time growth proxy.");
+
+  const hyg = price(quotes, "HYG");
+  const lqd = price(quotes, "LQD");
+  push("hyg_lqd", { en: "High yield / investment grade", zh: "高收益/投资级" }, hyg !== null && lqd !== null ? Number((hyg / lqd).toFixed(4)) : null,
+    "Falling means credit is repricing risk; weak balance sheets feel this before equity does.");
+
+  const rsp = price(quotes, "RSP");
+  const spy = price(quotes, "SPY");
+  push("breadth_rsp_spy", { en: "Equal weight / cap weight", zh: "等权重/市值加权" }, rsp !== null && spy !== null ? Number((rsp / spy).toFixed(4)) : null,
+    "Falling means the index is being carried by its largest members rather than by broad participation.");
+
+  return out;
+}
+
+export async function getMacroSnapshot(args = {}) {
+  const requested = Array.isArray(args?.blocks) && args.blocks.length ? args.blocks : MACRO_BLOCKS.map((b) => b.id);
+  const unknown = requested.filter((id) => !MACRO_BLOCKS.some((b) => b.id === id));
+  if (unknown.length) {
+    throw invalidParams(`unknown macro block(s): ${unknown.join(", ")}. Available: ${MACRO_BLOCKS.map((b) => b.id).join(", ")}`);
+  }
+  const blocks = MACRO_BLOCKS.filter((block) => requested.includes(block.id));
+  const symbols = [...new Set(blocks.flatMap((block) => block.members.map((m) => m.symbol)))];
+
+  const results = await Promise.all(symbols.map((symbol) => fetchQuote(symbol).catch((error) => ({
+    query: symbol,
+    error: String(error?.message || error),
+  }))));
+  const quotes = new Map(symbols.map((symbol, index) => [symbol, results[index]]));
+
+  const unavailable = [];
+  const rendered = blocks.map((block) => ({
+    id: block.id,
+    title: block.title,
+    why_it_matters: block.why,
+    members: block.members.map((member) => {
+      const quote = quotes.get(member.symbol);
+      if (!quote || quote.error) unavailable.push(`${member.label} (${member.symbol})`);
+      return { ...member, quote };
+    }),
+  }));
+
+  return {
+    as_of: new Date().toISOString(),
+    blocks: rendered,
+    derived: derived(quotes),
+    unavailable,
+    disclaimer:
+      "Keyless delayed market data (Yahoo/Stooq, ~15m or EOD). These are observations, not a regime call: "
+      + "read them, do not report them. Anything in `unavailable` is a data gap and belongs in open_questions, "
+      + "never a number filled in from memory.",
+  };
+}