- {currentContent.split("\n").map((line, i) => {
- const trimmed = line.trim();
- if (!trimmed) return
;
+ {hasHtml && (
+
+ )}
- // Detect headers (all-caps lines or lines starting with "Item")
- const isHeader = /^(Item\s+\d|ITEM\s+\d)/i.test(trimmed) ||
- (trimmed.length < 80 && trimmed === trimmed.toUpperCase() && /[A-Z]/.test(trimmed));
- const isBullet = /^[•\-\*●]\s/.test(trimmed) || /^\d+\.\s/.test(trimmed);
-
- if (isHeader) {
- return (
-
- {trimmed}
-
- );
- }
- if (isBullet) {
- return (
-
- {trimmed}
-
- );
- }
- return (
-
- {trimmed}
-
- );
- })}
+ {!hasHtml && currentContent && (
+
+
+ Plain text (cached) — same source as AI Summary; formatted HTML viewer is optional.
+
+
+ {currentContent}
-
- ) : (
-
- No content available for this section.
)}
diff --git a/atlas-terminal/apps/web/src/app/global-error.tsx b/atlas-terminal/apps/web/src/app/global-error.tsx
new file mode 100644
index 0000000..0f7c9dc
--- /dev/null
+++ b/atlas-terminal/apps/web/src/app/global-error.tsx
@@ -0,0 +1,37 @@
+"use client";
+
+/**
+ * Root error UI when the root layout fails. Must define html/body (Next.js requirement).
+ */
+export default function GlobalError({
+ error,
+ reset,
+}: {
+ error: Error & { digest?: string };
+ reset: () => void;
+}) {
+ return (
+
+
+
ATLAS Terminal — fatal error
+
{error.message || "Unknown error"}
+
reset()}
+ style={{
+ marginTop: 16,
+ padding: "8px 16px",
+ background: "#00d4aa",
+ color: "#0a0a0f",
+ border: "none",
+ borderRadius: 6,
+ fontWeight: 600,
+ cursor: "pointer",
+ }}
+ >
+ Try again
+
+
+
+ );
+}
diff --git a/atlas-terminal/apps/web/src/app/globals.css b/atlas-terminal/apps/web/src/app/globals.css
index 622504e..88eeb39 100644
--- a/atlas-terminal/apps/web/src/app/globals.css
+++ b/atlas-terminal/apps/web/src/app/globals.css
@@ -21,6 +21,53 @@ body {
font-family: "Inter", system-ui, sans-serif;
}
+:root {
+ --text-primary: #f3f4f6;
+ --text-secondary: #9ca3af;
+ --border-color: #2a2a3a;
+ --bg-card: #1a1a26;
+}
+
+.sec-viewer-container {
+ font-size: 0.875rem;
+ line-height: 1.65;
+ color: var(--text-primary);
+ background: transparent;
+}
+
+.sec-viewer-container [id^="sec-item-"] {
+ scroll-margin-top: 0.75rem;
+}
+
+.sec-viewer-container,
+.sec-viewer-container * {
+ background-color: transparent !important;
+ color: var(--text-primary) !important;
+}
+
+.sec-viewer-container a {
+ color: #4da6ff !important;
+ text-decoration: underline;
+}
+
+.sec-viewer-container table {
+ border-collapse: collapse;
+ width: max-content;
+ max-width: none;
+}
+
+.sec-viewer-container th,
+.sec-viewer-container td {
+ border: 1px solid var(--border-color) !important;
+ padding: 0.35rem 0.5rem !important;
+ vertical-align: top;
+}
+
+.sec-viewer-container img {
+ max-width: 100%;
+ height: auto;
+}
+
::-webkit-scrollbar {
width: 6px;
}
diff --git a/atlas-terminal/apps/web/src/app/layout.tsx b/atlas-terminal/apps/web/src/app/layout.tsx
index 717a88e..b52ec41 100644
--- a/atlas-terminal/apps/web/src/app/layout.tsx
+++ b/atlas-terminal/apps/web/src/app/layout.tsx
@@ -1,8 +1,6 @@
import type { Metadata } from "next";
import "./globals.css";
-import { Sidebar } from "./components/sidebar";
-import { TickerBar } from "./components/ticker-bar";
-import { ChatPanel } from "./components/chat-panel";
+import { AppShell } from "./components/app-shell";
export const metadata: Metadata = {
title: "ATLAS Terminal",
@@ -19,15 +17,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
rel="stylesheet"
/>
-
-
-
-
- {children}
-
-
+
+
{children}
);
diff --git a/atlas-terminal/apps/web/src/app/lib/filing-jurisdiction.ts b/atlas-terminal/apps/web/src/app/lib/filing-jurisdiction.ts
new file mode 100644
index 0000000..7480018
--- /dev/null
+++ b/atlas-terminal/apps/web/src/app/lib/filing-jurisdiction.ts
@@ -0,0 +1,9 @@
+/** Match server `infer_filing_jurisdiction` for Filings page routing. */
+export type FilingJurisdiction = "SEC" | "DART" | "EDINET";
+
+export function inferFilingJurisdiction(ticker: string): FilingJurisdiction {
+ const t = (ticker || "").trim().toUpperCase();
+ if (t.endsWith(".KS") || t.endsWith(".KQ")) return "DART";
+ if (t.endsWith(".T")) return "EDINET";
+ return "SEC";
+}
diff --git a/atlas-terminal/apps/web/src/app/lib/ticker-alias.ts b/atlas-terminal/apps/web/src/app/lib/ticker-alias.ts
index 3c9951b..b94757f 100644
--- a/atlas-terminal/apps/web/src/app/lib/ticker-alias.ts
+++ b/atlas-terminal/apps/web/src/app/lib/ticker-alias.ts
@@ -1,4 +1,7 @@
const TICKER_ALIASES: Record
= {
+ // Equities (natural language -> Yahoo suffix)
+ samsung: "005930.KS",
+
// Commodities (natural language -> futures ticker)
gold: "GC=F",
silver: "SI=F",
diff --git a/atlas-terminal/apps/web/src/app/lib/use-ticker.ts b/atlas-terminal/apps/web/src/app/lib/use-ticker.ts
index e80e695..3a2fb4d 100644
--- a/atlas-terminal/apps/web/src/app/lib/use-ticker.ts
+++ b/atlas-terminal/apps/web/src/app/lib/use-ticker.ts
@@ -6,16 +6,17 @@ const DEFAULT_TICKER = "AAPL";
const STORAGE_KEY = "atlas_active_ticker";
const EVENT_NAME = "atlas-ticker-change";
-function getInitialTicker(): string {
- if (typeof window === "undefined") return DEFAULT_TICKER;
- const saved = localStorage.getItem(STORAGE_KEY) || DEFAULT_TICKER;
- return normalizeTickerInput(saved);
-}
-
export function useTicker() {
- const [ticker, setTickerState] = useState(getInitialTicker);
+ // Must match server render: never read localStorage in useState initializer — hydration mismatch → white screen.
+ const [ticker, setTickerState] = useState(DEFAULT_TICKER);
useEffect(() => {
+ const saved = localStorage.getItem(STORAGE_KEY);
+ if (saved) {
+ const n = normalizeTickerInput(saved);
+ if (n) setTickerState(n);
+ }
+
const handler = (e: Event) => {
const detail = (e as CustomEvent).detail;
if (detail) setTickerState(detail);
diff --git a/atlas-terminal/apps/web/src/app/macro/page.tsx b/atlas-terminal/apps/web/src/app/macro/page.tsx
new file mode 100644
index 0000000..747ec7b
--- /dev/null
+++ b/atlas-terminal/apps/web/src/app/macro/page.tsx
@@ -0,0 +1,315 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { MacroCycleHeatmap, type MacroSnapshot } from "../components/markets/MacroCycleHeatmap";
+import { OECDCycleChart, type OECDData } from "../components/markets/OECDCycleChart";
+import { KoreaMonitor } from "../components/markets/KoreaMonitor";
+import { EconomicCalendar } from "../components/markets/EconomicCalendar";
+import { GlobalMacroQuadrantChart, type QuadrantPoint } from "../components/macro/GlobalMacroQuadrantChart";
+import { YieldFxDualAxisChart, type YieldFxRow } from "../components/macro/YieldFxDualAxisChart";
+import { SmartMoneyPanel } from "../components/macro/SmartMoneyPanel";
+
+const FRED_PRESETS = [
+ { id: "UNRATE", label: "US Unemployment %" },
+ { id: "CPIAUCSL", label: "US CPI (All Urban)" },
+ { id: "DFF", label: "Fed Funds Effective" },
+ { id: "T10Y2Y", label: "10Y-2Y Treasury spread" },
+];
+
+interface FredPoint {
+ date: string;
+ value: number;
+}
+
+type MacroTab = "fred" | "cycle" | "oecd" | "korea" | "calendar";
+
+export default function MacroPage() {
+ const [series, setSeries] = useState("UNRATE");
+ const [rows, setRows] = useState([]);
+ const [loading, setLoading] = useState(true);
+ const [err, setErr] = useState(null);
+
+ const [tab, setTab] = useState("fred");
+ const [snap, setSnap] = useState(null);
+ const [snapErr, setSnapErr] = useState(null);
+ const [oecd, setOecd] = useState(null);
+
+ const [classicOpen, setClassicOpen] = useState(false);
+
+ const [quadPoints, setQuadPoints] = useState([]);
+ const [quadErr, setQuadErr] = useState(null);
+
+ const [yieldPair, setYieldPair] = useState<"usdjpy" | "eurusd" | "usdkrw">("usdjpy");
+ const [yieldRows, setYieldRows] = useState([]);
+ const [yieldErr, setYieldErr] = useState(null);
+
+ const [roroZ, setRoroZ] = useState(null);
+ const [roroLabel, setRoroLabel] = useState(null);
+ const [copperGold, setCopperGold] = useState<
+ { date: string; ratio: number; ratio_ma20?: number }[]
+ >([]);
+ const [smartErr, setSmartErr] = useState(null);
+
+ useEffect(() => {
+ setLoading(true);
+ setErr(null);
+ fetch(`/api/macro/fred/${encodeURIComponent(series)}`)
+ .then((r) => (r.ok ? r.json() : Promise.reject(new Error(String(r.status)))))
+ .then((j) => {
+ setRows(Array.isArray(j.data) ? j.data : []);
+ setLoading(false);
+ })
+ .catch(() => {
+ setErr("Failed to load FRED series.");
+ setLoading(false);
+ });
+ }, [series]);
+
+ useEffect(() => {
+ fetch("/api/macro/snapshot")
+ .then((r) => (r.ok ? r.json() : null))
+ .then((j) => {
+ if (!j || typeof j !== "object") {
+ setSnap(null);
+ return;
+ }
+ if (j.error) setSnapErr(String(j.error));
+ else setSnapErr(null);
+ setSnap({
+ updated_at: j.updated_at ?? null,
+ cycle_score: typeof j.cycle_score === "number" ? j.cycle_score : 0,
+ regime: String(j.regime ?? "—"),
+ cycle_heatmap: Array.isArray(j.cycle_heatmap) ? j.cycle_heatmap : [],
+ country_heatmap: Array.isArray(j.country_heatmap) ? j.country_heatmap : [],
+ asset_valuation: Array.isArray(j.asset_valuation) ? j.asset_valuation : [],
+ });
+ })
+ .catch(() => setSnap(null));
+ }, []);
+
+ useEffect(() => {
+ fetch("/api/macro/oecd/cli")
+ .then((r) => (r.ok ? r.json() : null))
+ .then((j) => setOecd(j && typeof j === "object" ? j : null))
+ .catch(() => setOecd(null));
+ }, []);
+
+ useEffect(() => {
+ setQuadErr(null);
+ fetch("/api/macro/quadrant")
+ .then((r) => (r.ok ? r.json() : null))
+ .then((j) => {
+ if (!j || typeof j !== "object") {
+ setQuadPoints([]);
+ return;
+ }
+ if (j.error) setQuadErr(String(j.error));
+ setQuadPoints(Array.isArray(j.points) ? j.points : []);
+ })
+ .catch(() => setQuadPoints([]));
+ }, []);
+
+ useEffect(() => {
+ setYieldErr(null);
+ fetch(`/api/macro/yield-fx?pair=${encodeURIComponent(yieldPair)}`)
+ .then((r) => (r.ok ? r.json() : null))
+ .then((j) => {
+ if (!j || typeof j !== "object") {
+ setYieldRows([]);
+ return;
+ }
+ if (j.error) setYieldErr(String(j.error));
+ setYieldRows(Array.isArray(j.series) ? j.series : []);
+ })
+ .catch(() => setYieldRows([]));
+ }, [yieldPair]);
+
+ useEffect(() => {
+ setSmartErr(null);
+ fetch("/api/macro/smart-money")
+ .then((r) => (r.ok ? r.json() : null))
+ .then((j) => {
+ if (!j || typeof j !== "object") {
+ setRoroZ(null);
+ setRoroLabel(null);
+ setCopperGold([]);
+ return;
+ }
+ if (j.error) setSmartErr(String(j.error));
+ setRoroZ(typeof j.roro_z === "number" ? j.roro_z : null);
+ setRoroLabel(j.roro_label != null ? String(j.roro_label) : null);
+ setCopperGold(Array.isArray(j.copper_gold) ? j.copper_gold : []);
+ })
+ .catch(() => {
+ setRoroZ(null);
+ setRoroLabel(null);
+ setCopperGold([]);
+ });
+ }, []);
+
+ const tabs: { key: MacroTab; label: string }[] = [
+ { key: "fred", label: "FRED" },
+ { key: "cycle", label: "Cycle & valuation" },
+ { key: "oecd", label: "OECD CLI" },
+ { key: "korea", label: "Korea" },
+ { key: "calendar", label: "Calendar" },
+ ];
+
+ return (
+
+
+
Global Macro & Smart Money
+
+ Growth vs inflation quadrant (FRED / OECD), US–peer 10Y spreads vs FX (FRED + Yahoo), and copper/gold with a
+ VIX + bond-vol RORO gauge. Quantitative series are computed in Python only.
+
+
+
+
+
+
+
Global macro quadrant
+
3M momentum Z-scores (growth vs inflation).
+ {quadErr && (
+
Warning: {quadErr}
+ )}
+
+
+
+
+
+
Yield spread vs FX
+
+ {(["usdjpy", "eurusd", "usdkrw"] as const).map((p) => (
+ setYieldPair(p)}
+ className={`px-2 py-1 rounded text-xs font-mono border ${
+ yieldPair === p
+ ? "bg-accent-green/15 border-accent-green text-accent-green"
+ : "border-border text-text-secondary hover:bg-bg-hover"
+ }`}
+ >
+ {p.toUpperCase()}
+
+ ))}
+
+
+ {yieldErr && (
+
Warning: {yieldErr}
+ )}
+
+
+
+
+
Smart money & RORO
+
HG/GC ratio and composite risk Z-score.
+ {smartErr && (
+
Warning: {smartErr}
+ )}
+
+
+
+
+
+
+
setClassicOpen(!classicOpen)}
+ className="w-full text-left px-4 py-3 text-sm font-medium text-text-primary hover:bg-bg-hover flex justify-between items-center"
+ >
+ Classic macro tools
+ {classicOpen ? "▼" : "▶"}
+
+ {classicOpen && (
+
+
+ {tabs.map((t) => (
+ setTab(t.key)}
+ className={`px-3 py-1.5 rounded-md text-sm font-medium ${
+ tab === t.key ? "bg-accent-green text-bg-primary" : "text-text-secondary hover:text-text-primary"
+ }`}
+ >
+ {t.label}
+
+ ))}
+
+
+ {tab === "fred" && (
+ <>
+
+ {FRED_PRESETS.map((p) => (
+ setSeries(p.id)}
+ className={`px-3 py-1.5 rounded-md text-sm font-mono border ${
+ series === p.id
+ ? "bg-accent-green/15 border-accent-green text-accent-green"
+ : "bg-bg-card border-border text-text-secondary hover:bg-bg-hover"
+ }`}
+ >
+ {p.label}
+
+ ))}
+
+
+ {loading ? (
+
Loading data...
+ ) : err ? (
+
{err}
+ ) : (
+
+
+ {series} — {rows.length} observations (recent last)
+
+
+
+
+
+ Date
+ Value
+
+
+
+ {[...rows].reverse().slice(0, 60).map((r) => (
+
+ {r.date}
+ {r.value}
+
+ ))}
+
+
+
+
+ )}
+
+ )}
+
+ {tab === "cycle" && (
+
+ {snapErr && (
+
+ Snapshot warning: {snapErr}
+
+ )}
+
+
+ )}
+
+ {tab === "oecd" &&
}
+
+ {tab === "korea" &&
}
+
+ {tab === "calendar" &&
}
+
+ )}
+
+
();
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(upper)) !== null) {
+ const w = m[1];
+ if (STOPWORDS.has(w)) continue;
+ found.add(w);
+ }
+ return Array.from(found).slice(0, 16);
+}
+
+/** Many publishers (Yahoo, Bloomberg, WSJ, …) send X-Frame-Options / CSP so embedded iframes show a blank/broken page. */
+function isIframeEmbeddingBlocked(url: string): boolean {
+ try {
+ const host = new URL(url).hostname.toLowerCase().replace(/^www\./, "");
+ const suffixes = [
+ "yahoo.com",
+ "yahoo.co.jp",
+ "bloomberg.com",
+ "bloomberg.net",
+ "wsj.com",
+ "reuters.com",
+ "ft.com",
+ "cnbc.com",
+ "marketwatch.com",
+ "seekingalpha.com",
+ "nytimes.com",
+ "washingtonpost.com",
+ "theguardian.com",
+ "bbc.com",
+ "bbc.co.uk",
+ "forbes.com",
+ "investing.com",
+ "apnews.com",
+ "afp.com",
+ ];
+ return suffixes.some((s) => host === s || host.endsWith(`.${s}`));
+ } catch {
+ return true;
+ }
+}
+
+function matchesCategory(cat: CategoryFilter, title: string, summary: string): boolean {
+ const t = `${title} ${summary}`;
+ if (cat === "all") return true;
+ if (cat === "earnings") return /earnings|EPS|guidance|beat|miss|revenue|quarter|Q[1-4]\s/i.test(t);
+ if (cat === "fed") return /fed|FOMC|Powell|rate cut|rate hike|central bank/i.test(t);
+ if (cat === "rates") return /treasury|yield|bond|10-?year|inflation|CPI|PCE/i.test(t);
+ if (cat === "crypto") return /bitcoin|btc|eth|ethereum|crypto|solana|coinbase/i.test(t);
+ if (cat === "stocks") return /stock|shares|Nasdaq|NYSE|S&P|equity|trading|investor/i.test(t);
+ return true;
+}
+
+interface QuoteRow {
+ current_price: number | null;
+ change_pct: number | null;
+}
+
export default function NewsPage() {
const { ticker } = useTicker();
const [news, setNews] = useState([]);
const [loading, setLoading] = useState(true);
- const [selectedIdx, setSelectedIdx] = useState(null);
+ const [selected, setSelected] = useState(null);
+ const [category, setCategory] = useState("all");
+ const [keyword, setKeyword] = useState("");
+ const [mentionQuotes, setMentionQuotes] = useState>({});
useEffect(() => {
setLoading(true);
- setSelectedIdx(null);
+ setSelected(null);
fetch(`/api/news/${ticker}`)
.then((r) => (r.ok ? r.json() : []))
.then((data) => {
@@ -28,6 +101,52 @@ export default function NewsPage() {
.catch(() => setLoading(false));
}, [ticker]);
+ const filtered = useMemo(() => {
+ const kw = keyword.trim().toLowerCase();
+ return news.filter((item) => {
+ if (!matchesCategory(category, item.title, item.summary || "")) return false;
+ if (!kw) return true;
+ const blob = `${item.title} ${item.summary || ""}`.toLowerCase();
+ return blob.includes(kw);
+ });
+ }, [news, category, keyword]);
+
+ useEffect(() => {
+ if (!selected) {
+ setMentionQuotes({});
+ return;
+ }
+ const syms = extractTickers(`${selected.title} ${selected.summary || ""}`).filter((s) => s !== ticker.toUpperCase());
+ const take = syms.slice(0, 8);
+ if (take.length === 0) {
+ setMentionQuotes({});
+ return;
+ }
+ let cancelled = false;
+ Promise.all(
+ take.map((sym) =>
+ fetch(`/api/market/quote/${encodeURIComponent(sym)}`)
+ .then((r) => (r.ok ? r.json() : null))
+ .then((j) => ({ sym, j }))
+ )
+ ).then((rows) => {
+ if (cancelled) return;
+ const next: Record = {};
+ for (const { sym, j } of rows) {
+ if (j && typeof j === "object") {
+ next[sym] = {
+ current_price: typeof j.current_price === "number" ? j.current_price : null,
+ change_pct: typeof j.change_pct === "number" ? j.change_pct : null,
+ };
+ }
+ }
+ setMentionQuotes(next);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [selected, ticker]);
+
if (loading)
return (
@@ -35,7 +154,14 @@ export default function NewsPage() {
);
- const selectedItem = selectedIdx !== null ? news[selectedIdx] : null;
+ const cats: { key: CategoryFilter; label: string }[] = [
+ { key: "all", label: "All" },
+ { key: "earnings", label: "Earnings" },
+ { key: "fed", label: "Fed / policy" },
+ { key: "rates", label: "Rates / inflation" },
+ { key: "crypto", label: "Crypto" },
+ { key: "stocks", label: "Equities" },
+ ];
return (
@@ -43,73 +169,123 @@ export default function NewsPage() {
{ticker} News Feed
+
+ {cats.map((c) => (
+ setCategory(c.key)}
+ className={`px-3 py-1 rounded-md text-xs font-medium border ${
+ category === c.key
+ ? "bg-accent-green/15 border-accent-green text-accent-green"
+ : "bg-bg-card border-border text-text-secondary hover:border-accent-green/40"
+ }`}
+ >
+ {c.label}
+
+ ))}
+
+
- {news.length} articles from Finviz & Google News
+ {filtered.length} of {news.length} articles (Finviz, Google News, Yahoo)
- {/* Article List */}
- {news.length > 0 ? (
- news.map((item, i) => (
-
setSelectedIdx(i)}
- className={`cursor-pointer rounded-lg p-3 transition-all border ${
- selectedIdx === i
- ? "bg-accent-green/10 border-accent-green/50"
- : "bg-bg-card border-border hover:border-accent-green/30"
- }`}
- >
-
0 ? (
+ filtered.map((item) => {
+ const mentions = extractTickers(`${item.title} ${item.summary || ""}`).slice(0, 5);
+ return (
+ setSelected(item)}
+ className={`cursor-pointer rounded-lg p-3 transition-all border ${
+ selected?.url === item.url
+ ? "bg-accent-green/10 border-accent-green/50"
+ : "bg-bg-card border-border hover:border-accent-green/30"
}`}
>
- {item.title}
-
-
- {item.source && (
-
- {item.source}
-
+
+ {item.title}
+
+ {mentions.length > 0 && (
+
+ {mentions.map((m) => (
+
+ {m}
+
+ ))}
+
)}
-
- {item.published_at}
-
+
+ {item.source && (
+
+ {item.source}
+
+ )}
+ {item.published_at}
+
-
No news articles found
+ No articles match filters
)}
- {/* Article Content - Right Panel */}
- {selectedItem && (
+ {selected && (
- {/* Header */}
-
- {selectedItem.title}
-
+
{selected.title}
+ {Object.keys(mentionQuotes).length > 0 && (
+
+ {Object.entries(mentionQuotes).map(([sym, q]) => (
+
+ {sym}
+ {q.change_pct != null && (
+ = 0 ? " text-accent-green" : " text-accent-red"}>
+ {" "}
+ {q.change_pct >= 0 ? "+" : ""}
+ {q.change_pct.toFixed(2)}%
+
+ )}
+ {q.current_price != null && (
+ @ ${q.current_price.toFixed(2)}
+ )}
+
+ ))}
+
+ )}
- {/* Article Embed */}
-
-
+
+ {isIframeEmbeddingBlocked(selected.url) ? (
+
+
+ 이 출처(Yahoo·Bloomberg 등)는 보안 정책으로 미리보기 iframe 을
+ 허용하지 않습니다. 원문은 새 탭에서 열어 주세요.
+
+ {selected.summary ? (
+
+
Summary
+
{selected.summary}
+
+ ) : null}
+
+ 원문 열기 ↗
+
+
+ ) : (
+
+ )}
)}
diff --git a/atlas-terminal/apps/web/src/app/not-found.tsx b/atlas-terminal/apps/web/src/app/not-found.tsx
new file mode 100644
index 0000000..a5e1676
--- /dev/null
+++ b/atlas-terminal/apps/web/src/app/not-found.tsx
@@ -0,0 +1,16 @@
+import Link from "next/link";
+
+export default function NotFound() {
+ return (
+
+
404
+
This page does not exist.
+
+ Back to Overview
+
+
+ );
+}
diff --git a/atlas-terminal/apps/web/src/app/portfolio/page.tsx b/atlas-terminal/apps/web/src/app/portfolio/page.tsx
index e3fa94b..8363ed9 100644
--- a/atlas-terminal/apps/web/src/app/portfolio/page.tsx
+++ b/atlas-terminal/apps/web/src/app/portfolio/page.tsx
@@ -15,6 +15,7 @@ interface Position {
method?: string;
avg_price_currency?: string;
stock_currency?: string;
+ currency?: string;
account_currency?: string;
current_value_account?: number;
total_pnl?: number;
@@ -61,7 +62,7 @@ export default function PortfolioPage() {
const opts = Array.isArray(data?.options) ? data.options : [];
if (opts.length > 0) {
setExchangeOptions((prev) => ({ ...prev, [rowKey]: opts }));
- const def = opts.find((o) => o.default) || opts[0];
+ const def = opts.find((o: { default?: boolean; exchange: string }) => o.default) || opts[0];
setExchangeSelections((prev) => ({ ...prev, [rowKey]: def.exchange }));
}
});
diff --git a/atlas-terminal/apps/web/src/app/research/page.tsx b/atlas-terminal/apps/web/src/app/research/page.tsx
index 07a424f..bc2f4d2 100644
--- a/atlas-terminal/apps/web/src/app/research/page.tsx
+++ b/atlas-terminal/apps/web/src/app/research/page.tsx
@@ -1,81 +1,49 @@
"use client";
+
import { useEffect, useState } from "react";
+import { ResearchGridLayout } from "../components/research/ResearchGridLayout";
+import type { ResearchDashboardPayload } from "../components/research/types";
import { useTicker } from "../lib/use-ticker";
-interface PiotroskiData {
- score?: number;
- details?: Record
;
-}
-
-interface RadarData {
- roe?: number;
- roa?: number;
- gross_margin?: number;
- current_ratio?: number;
- revenue_growth?: number;
-}
-
export default function ResearchPage() {
const { ticker } = useTicker();
const [assetType, setAssetType] = useState("equity");
- const [piotroski, setPiotroski] = useState(null);
- const [radar, setRadar] = useState(null);
- const [aiAnalysis, setAiAnalysis] = useState("");
- const [aiLoading, setAiLoading] = useState(false);
+ const [dashboard, setDashboard] = useState(null);
+ const [loadError, setLoadError] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
setLoading(true);
+ setLoadError(null);
Promise.all([
- fetch(`/api/market/piotroski/${ticker}`).then((r) => r.ok ? r.json() : null),
- fetch(`/api/market/radar/${ticker}`).then((r) => r.ok ? r.json() : null),
- fetch(`/api/market/overview/${ticker}`).then((r) => r.ok ? r.json() : null),
- ]).then(([p, r, o]) => {
- setPiotroski(p);
- setRadar(r);
- setAssetType(o?.asset_type || "equity");
- setLoading(false);
- }).catch(() => setLoading(false));
+ fetch(`/api/market/overview/${ticker}`).then((r) => (r.ok ? r.json() : { asset_type: "equity" })),
+ fetch(`/api/research/dashboard/${encodeURIComponent(ticker)}`).then(async (r) => {
+ if (!r.ok) {
+ const errText = await r.text();
+ throw new Error(errText || `HTTP ${r.status}`);
+ }
+ return r.json();
+ }),
+ ])
+ .then(([overview, dash]) => {
+ setAssetType(overview?.asset_type || "equity");
+ setDashboard(dash as ResearchDashboardPayload);
+ })
+ .catch(() => {
+ setLoadError("대시보드 데이터를 불러오지 못했습니다.");
+ setDashboard(null);
+ })
+ .finally(() => setLoading(false));
}, [ticker]);
- async function runAiAnalysis() {
- const apiKey = localStorage.getItem("atlas_gemini_key") || "";
- if (!apiKey) {
- setAiAnalysis("Please set your Gemini API key in Settings first.");
- return;
- }
- setAiLoading(true);
- try {
- const res = await fetch("/api/analysis/strategy", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({ ticker, question: `Comprehensive research analysis of ${ticker}: competitive position, growth catalysts, and risks`, api_key: apiKey }),
- });
- if (res.ok) {
- const data = await res.json();
- setAiAnalysis(typeof data === "string" ? data : data.analysis || JSON.stringify(data));
- } else {
- setAiAnalysis("API error. Check your Gemini key in Settings.");
- }
- } catch {
- setAiAnalysis("Connection error.");
- }
- setAiLoading(false);
+ if (loading) {
+ return (
+
+ );
}
- if (loading) return ;
-
- const fScore = piotroski?.score ?? 0;
- const fColor = fScore >= 7 ? "text-accent-green" : fScore >= 4 ? "text-accent-yellow" : "text-accent-red";
-
- const radarMetrics = radar ? [
- { label: "ROE", value: radar.roe, max: 30 },
- { label: "ROA", value: radar.roa, max: 20 },
- { label: "Gross Margin", value: radar.gross_margin, max: 100 },
- { label: "Current Ratio", value: radar.current_ratio, max: 3 },
- { label: "Revenue Growth", value: radar.revenue_growth, max: 50 },
- ] : [];
-
return (
@@ -83,90 +51,38 @@ export default function ResearchPage() {
{assetType === "equity" ? (
-
- {/* Piotroski F-Score */}
-
-
Piotroski F-Score
-
{fScore}/9
-
- {fScore >= 7 ? "Strong" : fScore >= 4 ? "Moderate" : "Weak"} financial strength
+ loadError ? (
+
{loadError}
+ ) : dashboard ? (
+ <>
+ {dashboard.error && (
+
+ {dashboard.error} — 일부 위젯이 비어 있을 수 있습니다.
+
+ )}
+
+
+ ) : (
+
+ 대시보드 데이터가 없습니다. API 응답을 확인하거나 티커를 바꿔 보세요.
- {piotroski?.details && (
-
- {Object.entries(piotroski.details).map(([key, val]) => (
-
- {key}
-
- {val.pass ? "✓" : "✗"}
-
-
- ))}
-
- )}
-
-
- {/* Financial Radar */}
-
-
Financial Radar
- {radarMetrics.length > 0 ? (
-
- {radarMetrics.map((m) => {
- const pct = m.value != null ? Math.min((m.value / m.max) * 100, 100) : 0;
- const color = pct > 66 ? "bg-accent-green" : pct > 33 ? "bg-accent-yellow" : "bg-accent-red";
- return (
-
-
- {m.label}
- {m.value?.toFixed(1) ?? "—"}%
-
-
-
- );
- })}
-
- ) : (
-
No data available
- )}
-
-
+ )
) : assetType === "etf" ? (
ETF Research
- Holdings Analysis, Sector Breakdown, Overlap Analysis를 우선 제공합니다.
- Piotroski/F-Score 및 기업 재무 레이더는 ETF에 적용되지 않습니다.
+ Holdings Analysis, Sector Breakdown, Overlap Analysis를 우선 제공합니다. Piotroski/F-Score 및 기업 재무
+ 대시보드는 ETF에 적용되지 않습니다.
) : (
Commodity Research
- Seasonal Analysis와 Supply/Demand 요인을 중심으로 분석합니다.
- 주식 전용 지표(F-Score, DuPont)는 표시하지 않습니다.
+ Seasonal Analysis와 Supply/Demand 요인을 중심으로 분석합니다. 주식 전용 지표는 표시하지 않습니다.
)}
-
- {/* AI Analysis */}
-
-
-
AI Research Analysis
-
- {aiLoading ? "Analyzing..." : "Run Analysis"}
-
-
- {aiAnalysis ? (
-
{aiAnalysis}
- ) : (
-
Click "Run Analysis" to generate AI-powered research report.
- )}
-
);
}
diff --git a/atlas-terminal/apps/web/src/app/screener/page.tsx b/atlas-terminal/apps/web/src/app/screener/page.tsx
index a182edc..d15e97b 100644
--- a/atlas-terminal/apps/web/src/app/screener/page.tsx
+++ b/atlas-terminal/apps/web/src/app/screener/page.tsx
@@ -1,5 +1,6 @@
"use client";
-import { useState } from "react";
+
+import { useEffect, useRef, useState } from "react";
interface ScreenerRow {
ticker: string;
@@ -18,6 +19,11 @@ interface BacktestResult {
benchmark_return_pct?: number;
alpha?: number;
sharpe_ratio?: number;
+ max_drawdown_pct?: number;
+ equity_curve?: number[];
+ benchmark_curve?: number[];
+ dates?: string[];
+ benchmark_ticker?: string;
}
export default function ScreenerPage() {
@@ -29,11 +35,14 @@ export default function ScreenerPage() {
const [divMin, setDivMin] = useState("");
const [btTicker, setBtTicker] = useState("AAPL");
+ const [btBenchmark, setBtBenchmark] = useState("SPY");
+ const [rebalanceMonths, setRebalanceMonths] = useState("");
const [strategy, setStrategy] = useState("sma_crossover");
const [startDate, setStartDate] = useState("2024-01-01");
const [endDate, setEndDate] = useState("2026-03-01");
const [btResult, setBtResult] = useState
(null);
const [btLoading, setBtLoading] = useState(false);
+ const chartRef = useRef(null);
async function runScreener() {
setLoading(true);
@@ -59,15 +68,20 @@ export default function ScreenerPage() {
async function runBacktest() {
setBtLoading(true);
try {
+ const body: Record = {
+ ticker: btTicker,
+ strategy,
+ start_date: startDate,
+ end_date: endDate,
+ benchmark_ticker: btBenchmark || "SPY",
+ };
+ const rm = parseInt(rebalanceMonths, 10);
+ if (!Number.isNaN(rm) && rm > 0) body.rebalance_months = rm;
+
const res = await fetch("/api/screener/backtest", {
method: "POST",
headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- ticker: btTicker,
- strategy,
- start_date: startDate,
- end_date: endDate,
- }),
+ body: JSON.stringify(body),
});
setBtResult(await res.json());
} catch {
@@ -77,18 +91,67 @@ export default function ScreenerPage() {
}
}
+ useEffect(() => {
+ if (!btResult?.equity_curve || !btResult.benchmark_curve || !btResult.dates || !chartRef.current) return;
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ let chart: any = null;
+ const el = chartRef.current;
+ let onResize: (() => void) | null = null;
+
+ import("lightweight-charts")
+ .then(({ createChart }) => {
+ if (!el) return;
+ el.innerHTML = "";
+ chart = createChart(el, {
+ width: el.clientWidth,
+ height: 320,
+ layout: { background: { color: "#1A1A26" }, textColor: "#9CA3AF" },
+ grid: { vertLines: { color: "#2A2A3A" }, horzLines: { color: "#2A2A3A" } },
+ crosshair: { mode: 0 },
+ timeScale: { borderColor: "#2A2A3A" },
+ });
+ const strat = chart.addLineSeries({ color: "#00D4AA", lineWidth: 2 });
+ strat.setData(
+ btResult.dates!.map((d, i) => ({
+ time: d as string & { __brand?: "Time" },
+ value: btResult.equity_curve![i],
+ }))
+ );
+ const bench = chart.addLineSeries({ color: "#4DA6FF", lineWidth: 2 });
+ bench.setData(
+ btResult.dates!.map((d, i) => ({
+ time: d as string & { __brand?: "Time" },
+ value: btResult.benchmark_curve![i],
+ }))
+ );
+ chart.timeScale().fitContent();
+ onResize = () => {
+ if (el && chart) chart.applyOptions({ width: el.clientWidth });
+ };
+ window.addEventListener("resize", onResize);
+ })
+ .catch(() => {});
+
+ return () => {
+ if (onResize) window.removeEventListener("resize", onResize);
+ if (chart) chart.remove();
+ };
+ }, [btResult]);
+
return (
Stock Screener
setTab("screener")}
className={`px-4 py-2 rounded-md text-sm font-medium ${tab === "screener" ? "bg-accent-green text-bg-primary" : "text-text-secondary"}`}
>
Screener
setTab("backtest")}
className={`px-4 py-2 rounded-md text-sm font-medium ${tab === "backtest" ? "bg-accent-green text-bg-primary" : "text-text-secondary"}`}
>
@@ -99,10 +162,25 @@ export default function ScreenerPage() {
{tab === "screener" ? (
-
+
{loading ? "Running..." : "Run Screener"}
@@ -111,7 +189,9 @@ export default function ScreenerPage() {
{["Ticker", "Name", "Sector", "Price", "P/E", "MCap", "Change"].map((h) => (
- {h}
+
+ {h}
+
))}
@@ -124,7 +204,7 @@ export default function ScreenerPage() {
{r.price != null ? `$${r.price.toFixed(2)}` : "—"}
{r.pe != null ? r.pe.toFixed(1) : "—"}
{r.market_cap ? `${(r.market_cap / 1e9).toFixed(1)}B` : "—"}
-
= 0) ? "text-accent-green" : "text-accent-red"}`}>
+ = 0 ? "text-accent-green" : "text-accent-red"}`}>
{r.change_pct != null ? `${r.change_pct >= 0 ? "+" : ""}${r.change_pct.toFixed(2)}%` : "—"}
@@ -134,9 +214,26 @@ export default function ScreenerPage() {
) : (
-
+
diff --git a/atlas-terminal/apps/web/src/app/technical/page.tsx b/atlas-terminal/apps/web/src/app/technical/page.tsx
index ef36419..9969d92 100644
--- a/atlas-terminal/apps/web/src/app/technical/page.tsx
+++ b/atlas-terminal/apps/web/src/app/technical/page.tsx
@@ -56,6 +56,8 @@ export default function TechnicalPage() {
// Render chart using lightweight-charts
useEffect(() => {
if (!chartRef.current || bars.length === 0) return;
+ // v5 typings omit series helpers; runtime still exposes addCandlestickSeries etc.
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
let chart: any = null;
(async () => {
try {
diff --git a/atlas-terminal/claude.md b/atlas-terminal/claude.md
index 4239c3c..556a938 100644
--- a/atlas-terminal/claude.md
+++ b/atlas-terminal/claude.md
@@ -2,7 +2,7 @@
> 이 문서는 Claude Code 에이전트가 프로젝트를 빌드할 때 참조하는 마스터 가이드입니다.
> 모든 에이전트는 작업 시작 전 이 문서를 반드시 읽어야 합니다.
-> **마지막 수정: 2026-03-21**
+> **마지막 수정: 2026-03-26**
---
@@ -36,12 +36,18 @@
- Gemini 호출은 탭당 최대 1~2회로 제한
- 429 에러 시 `_generate_with_retry()`로 60초 대기 후 재시도
-### 2.3 다단계 폴백 체인
-모든 외부 API 호출은 아래 순서를 따른다:
-```
-yfinance (1순위) → yahooquery (2순위) → fast_info (3순위) → info (4순위)
-→ balance_sheet/cashflow (5순위) → TTM 분기 합산 (6순위) → 수동 입력 (최후)
-```
+### 2.3 다단계 폴백 체인 (기능별 — 코드와 일치)
+“한 줄 체인”이 아니라 **엔드포인트/서비스마다** 소스 순서가 다르다. 아래가 실제 구현 기준이다.
+
+| 영역 | 1순위 | 2순위 | 비고 |
+|------|--------|--------|------|
+| 가격·차트·`info`·배당 등 | yfinance | yahooquery | `market_data`, `technical`, 대부분 라우터 |
+| 연간 재무제표 (`/api/financials/.../statements`) | yfinance | yahooquery | 연간만 필터 |
+| DCF 입력·`market_fetcher` 연간 집계 | yahooquery (TTM 보강) | yfinance (분기 합산 등) | `server/services/market_fetcher.py` |
+| 히스토리컬 밸류·재무 비율·어닝콜 (선택) | FMP (`FMP_API_KEY` 있을 때만) | yahooquery `summary_detail` / `financial_data` | yfinance `info` — `server/services/fmp_client.py` |
+| 거시 (FRED/OECD/ECOS) | FRED 공개 CSV / ECOS 키 | — | `server/services/macro_fetcher.py` |
+
+레거시 서술(참고): 티커 메타/추정 등 일부 경로는 `fast_info` → `info` → 재무표 순으로 보강한다.
- 모든 숫자 파싱에 `_safe_float()` 사용 (`server/utils/safe_float.py`)
- 실패 시 빈 DataFrame 또는 None 반환, 절대 에러를 UI에 노출하지 않음
@@ -77,64 +83,124 @@ function getValue(periodData: Record
, key: string) {
atlas-terminal/
├── apps/web/ # Next.js 14 프론트엔드
│ ├── src/app/
-│ │ ├── layout.tsx # 루트 레이아웃 (3-panel: Sidebar + Main + ChatPanel)
-│ │ ├── page.tsx # Overview (Sector, DuPont, Altman Z)
+│ │ ├── layout.tsx # 루트 레이아웃 (AppShell 래퍼)
+│ │ ├── page.tsx # Overview — Multi-Asset (Equity/ETF/Commodity 자동분기)
│ │ ├── globals.css # Tailwind + Terminal Noir 기본 스타일
-│ │ ├── research/page.tsx # 10-K AI 분석 + Risk Factors
+│ │ ├── error.tsx # 세그먼트 레벨 에러 바운더리
+│ │ ├── global-error.tsx # 루트 레벨 에러 바운더리
+│ │ ├── not-found.tsx # 404 페이지
+│ │ ├── research/page.tsx # 리서치 그리드 (F-Score, DuPont, Sankey, Waterfall, Anomaly)
│ │ ├── valuation/page.tsx # 5-Tab: DCF, Sensitivity, Monte Carlo, Tornado, Reverse DCF
-│ │ ├── technical/page.tsx # TradingView 캔들차트 + RSI/MACD/Bollinger/Fibonacci/MA
-│ │ ├── markets/page.tsx # 재무제표 테이블 (YoY Growth + Margin %)
+│ │ ├── technical/page.tsx # TradingView 캔들차트 + RSI/MACD/Bollinger/Fibonacci/Ichimoku
+│ │ ├── markets/page.tsx # 재무제표 테이블 + 섹터 히트맵
+│ │ ├── macro/page.tsx # 거시 5탭(FRED/Cycle/OECD/Korea/Calendar) + Quadrant/YieldFX/SmartMoney
│ │ ├── earnings/page.tsx # EPS Beat/Miss + Revenue + Next Earnings
│ │ ├── news/page.tsx # Split-view: 기사 리스트 + iframe 원문
-│ │ ├── portfolio/page.tsx # 포지션 CRUD + Risk Metrics
-│ │ ├── filings/page.tsx # SEC 10-K 원문 (5개 섹션 탭 + AI 요약)
+│ │ ├── screener/page.tsx # 종목 스크리너 + 전략 백테스트
+│ │ ├── portfolio/page.tsx # 포지션 CRUD + Risk Metrics + OCR
+│ │ ├── filings/page.tsx # 공시 원문 — SEC/DART/EDINET 자동분기 (5탭 + AI 요약)
│ │ ├── settings/page.tsx # API Key 관리
│ │ ├── components/
-│ │ │ ├── sidebar.tsx # 좌측 네비게이션 (10개 메뉴)
+│ │ │ ├── app-shell.tsx # 3-panel 레이아웃 래퍼 (SSR-safe dynamic import)
+│ │ │ ├── sidebar.tsx # 좌측 네비게이션 (12개 메뉴)
│ │ │ ├── ticker-bar.tsx # 상단 실시간 지수 바 (S&P, NASDAQ, KOSPI, BTC)
-│ │ │ └── chat-panel.tsx # 우측 AI Copilot 채팅
+│ │ │ ├── chat-panel.tsx # 우측 AI Copilot 채팅
+│ │ │ ├── filings/
+│ │ │ │ └── FilingsViewer.tsx # 공시 뷰어 (IntersectionObserver scroll-spy)
+│ │ │ ├── macro/
+│ │ │ │ ├── GlobalMacroQuadrantChart.tsx # 성장 vs 인플레 Z-score 산점도
+│ │ │ │ ├── YieldFxDualAxisChart.tsx # US10Y 스프레드 vs FX 이중축
+│ │ │ │ └── SmartMoneyPanel.tsx # Copper/Gold + RORO 패널
+│ │ │ ├── markets/
+│ │ │ │ ├── HeatmapSection.tsx # 섹터 히트맵 (S&P/NASDAQ/KOSPI/FTSE)
+│ │ │ │ ├── EconomicCalendar.tsx # 글로벌 경제 이벤트
+│ │ │ │ ├── KoreaMonitor.tsx # 한국 경제 지표 (ECOS)
+│ │ │ │ ├── MacroCycleHeatmap.tsx # 매크로 사이클 히트맵
+│ │ │ │ └── OECDCycleChart.tsx # OECD CLI 차트
+│ │ │ ├── overview/
+│ │ │ │ ├── EquityOverview.tsx # 주식 오버뷰 (섹터, DuPont, Altman Z)
+│ │ │ │ ├── ETFOverview.tsx # ETF 오버뷰 (보유종목, 섹터비중)
+│ │ │ │ ├── CommodityOverview.tsx # 원자재 오버뷰 (계절성, 상관관계)
+│ │ │ │ ├── KpiSection.tsx # 분기 KPI 스파크라인
+│ │ │ │ └── PeerComparison.tsx # 동종업계 밸류에이션 비교
+│ │ │ └── research/
+│ │ │ ├── ResearchGridLayout.tsx # 12-col CSS 그리드 레이아웃
+│ │ │ ├── FScorePanel.tsx # Piotroski F-Score 이력 (9항목)
+│ │ │ ├── DuPontTree.tsx # 3-Factor ROE 분해 트리
+│ │ │ ├── SankeyWidget.tsx # 손익 Sankey (@nivo/sankey)
+│ │ │ ├── WaterfallWidget.tsx # 영업이익 워터폴 (@nivo/bar)
+│ │ │ ├── AnomalyChips.tsx # YoY 이상치 + Gemini 설명
+│ │ │ └── types.ts # 리서치 대시보드 타입 정의
│ │ └── lib/
-│ │ ├── use-ticker.ts # 티커 상태 훅 (localStorage + CustomEvent)
-│ │ └── api.ts # API 클라이언트 유틸
+│ │ ├── use-ticker.ts # 티커 상태 훅 (localStorage + CustomEvent, hydration-safe)
+│ │ ├── api.ts # API 클라이언트 유틸 (apiFetch, apiPost)
+│ │ ├── ticker-alias.ts # 자연어→티커 매핑 ("gold"→GC=F, "samsung"→005930.KS)
+│ │ └── filing-jurisdiction.ts # 티커→관할권 추론 (SEC/DART/EDINET)
│ ├── next.config.mjs # /api/* → localhost:8000 프록시
│ ├── tailwind.config.ts # Terminal Noir 컬러 토큰
│ └── package.json
│
├── server/ # FastAPI 백엔드
-│ ├── main.py # FastAPI app + 14개 라우터 등록
-│ ├── routers/ # API 엔드포인트 (14개 라우터)
-│ │ ├── analysis.py # POST /api/analysis — Gemini LLM 분석
+│ ├── main.py # FastAPI app + 21개 라우터 등록
+│ ├── routers/ # API 엔드포인트 (21개)
+│ │ ├── analysis.py # POST /api/analysis — Gemini LLM 분석 (strategy/risks/mda/forensic)
│ │ ├── chat.py # /api/chat — AI Copilot
│ │ ├── crypto.py # /api/crypto — 암호화폐 가격
-│ │ ├── earnings.py # /api/earnings/{ticker}/history|calendar|quarterly
+│ │ ├── dart.py # /api/dart — Korea DART 기업검색 + 사업보고서 섹션
+│ │ ├── earnings.py # /api/earnings — history|calendar|quarterly|transcript
│ │ ├── edgar.py # /api/edgar — SEC 10-K 다운로드 + 파싱
+│ │ ├── edinet.py # /api/edinet — Japan EDINET 링크 + 섹션 (optional key)
│ │ ├── estimates.py # /api/estimates — 애널리스트 추정치
-│ │ ├── financials.py # /api/financials/{ticker} — IS/BS/CF
+│ │ ├── financials.py # /api/financials — statements/highlights/kpi-history/ratios
+│ │ ├── fmp.py # /api/fmp — Key metrics, ratios (optional FMP key)
│ │ ├── fx.py # /api/fx — 환율
-│ │ ├── insider.py # /api/insider/{ticker} — 내부자 거래
-│ │ ├── market_data.py # /api/market — 주가/섹터/헬스체크
-│ │ ├── news.py # /api/news/{ticker} — Finviz + Google RSS
-│ │ ├── portfolio.py # /api/portfolio — CRUD + Risk
-│ │ ├── technical.py # /api/technical/{ticker} — 기술적 지표
-│ │ └── valuation.py # /api/valuation — DCF, Sensitivity, Monte Carlo, Tornado, Reverse DCF
-│ ├── services/ # 비즈니스 로직 (17개 서비스)
-│ │ ├── crypto_fetcher.py # Bithumb + Binance API
+│ │ ├── insider.py # /api/insider — 내부자 거래 + 기관보유
+│ │ ├── macro.py # /api/macro — FRED/OECD/ECOS/Quadrant/YieldFX/SmartMoney/Calendar
+│ │ ├── market_data.py # /api/market — 시세/섹터/헬스/트렌드/피어/Sankey/Radar/ETF/원자재
+│ │ ├── markets.py # /api/markets — 섹터 히트맵
+│ │ ├── news.py # /api/news — Finviz + Google + Yahoo RSS
+│ │ ├── portfolio.py # /api/portfolio — CRUD + Risk + OCR
+│ │ ├── research.py # /api/research — 퀀트 대시보드 (F-Score/DuPont/Sankey/Waterfall/Anomaly)
+│ │ ├── screener.py # /api/screener — 종목 검색 + 백테스트
+│ │ ├── technical.py # /api/technical — indicators/chart-data/fibonacci/ichimoku
+│ │ └── valuation.py # /api/valuation — DCF/Sensitivity/Monte Carlo/Tornado/Reverse DCF
+│ ├── services/ # 비즈니스 로직 (37개)
+│ │ ├── backtester.py # 전략 백테스트 (SMA/RSI/Buy&Hold)
+│ │ ├── cache.py # 인메모리 TTL 캐시 데코레이터
+│ │ ├── commodity_analysis.py # 원자재 계절성·상관관계
+│ │ ├── dart_fetcher.py # DART API 클라이언트 (기업검색)
+│ │ ├── dart_filing_service.py # DART 사업보고서 ZIP/XML → 섹션 매핑 + 캐시
│ │ ├── dcf_engine.py # excel_style_dcf, dcf_10y_2stage, reverse_dcf (scipy brentq)
+│ │ ├── economic_calendar.py # 경제 캘린더 데이터
+│ │ ├── ecos_fetcher.py # 한국은행 ECOS 매크로 데이터
+│ │ ├── edinet_filing_service.py # EDINET API v2 + 링크 폴백
+│ │ ├── etf_analysis.py # ETF 보유종목·섹터비중
+│ │ ├── exchange_resolver.py # 거래소 해석
│ │ ├── financial_metrics.py # DuPont, Altman Z, Piotroski F-Score
-│ │ ├── financial_metrics_ext.py # 확장 지표
-│ │ ├── fx_fetcher.py # 환율 데이터
-│ │ ├── gemini_analysis.py # Gemini 분석 로직
+│ │ ├── financial_metrics_ext.py # 확장 지표 (Sankey, Waterfall 데이터)
+│ │ ├── fmp_client.py # FMP API + Yahoo fallback snapshots
│ │ ├── gemini_service.py # Gemini API 래퍼 (retry, streaming)
-│ │ ├── market_data.py # 시장 데이터 서비스
-│ │ ├── market_fetcher.py # yfinance/yahooquery 폴백 체인
+│ │ ├── global_macro_quadrant.py # 성장 vs 인플레 Z-score 사분면
+│ │ ├── heatmap.py # 섹터 히트맵 데이터
+│ │ ├── kpi_history_service.py # 분기 KPI 시계열 (매출성장/마진/ROE/FCF)
+│ │ ├── macro_cycle.py # 매크로 사이클 분석 (FRED + World Bank)
+│ │ ├── macro_fetcher.py # FRED CSV + OECD + ECOS 매크로 데이터
+│ │ ├── market_fetcher.py # yfinance/yahooquery 폴백 체인 (DCF 입력)
+│ │ ├── market_overview.py # 시장 개요 데이터
│ │ ├── monte_carlo.py # run_monte_carlo_dcf (numpy, 5000 sims)
-│ │ ├── news_aggregator.py # RSS + Finviz + Google News
+│ │ ├── news_aggregator.py # Finviz scrape + Google/Yahoo RSS
+│ │ ├── oecd_cycle.py # OECD CLI via DBnomics
+│ │ ├── peer_comparison_service.py # 동종업계 밸류에이션 비교
+│ │ ├── research_dashboard.py # 리서치 대시보드 (F-Score/DuPont/Sankey/Waterfall/Anomaly)
│ │ ├── risk_metrics.py # VaR, Sharpe, Sortino, MDD, Beta, Correlation
+│ │ ├── screener.py # 종목 스크리너 로직
│ │ ├── screenshot_ocr.py # Gemini Vision OCR (포트폴리오 스크린샷)
│ │ ├── sec_parser.py # 10-K 다운로드 + HTML 파싱 + 섹션 추출 + 캐싱
+│ │ ├── sector_heatmap.py # 섹터 히트맵 계산
│ │ ├── sensitivity.py # build_sensitivity_matrix, build_tornado_data
-│ │ ├── technical_analysis.py # RSI, MACD, Bollinger, Ichimoku, ADX, Fibonacci
-│ │ └── text_chunker.py # smart_chunk, clean_text_for_llm
+│ │ ├── smart_money_service.py # Copper/Gold ratio + RORO 리스크 복합지수
+│ │ ├── text_chunker.py # smart_chunk, clean_text_for_llm
+│ │ └── yield_fx_service.py # US10Y 스프레드 vs FX (USDJPY/EURUSD/USDKRW)
│ ├── db/ # 데이터베이스 레이어
│ │ ├── unified_repo.py # SQLite/PostgreSQL 통합 인터페이스
│ │ ├── cache.py # 캐시 저장소
@@ -153,7 +219,7 @@ atlas-terminal/
│ │ └── context_builder.py # 컨텍스트 빌더
│ └── utils/
│ ├── safe_float.py # 안전한 숫자 파싱
-│ └── ticker_utils.py # 티커 유틸리티
+│ └── ticker_utils.py # 티커/자산유형 유틸리티
│
├── claude.md # 이 파일 (AI 에이전트 매뉴얼)
├── requirements.txt # Python 의존성
@@ -229,32 +295,50 @@ fontFamily: {
### 5.1 Market Data (`/api/market`)
| Method | Path | 설명 |
|--------|------|------|
+| GET | `/api/market/indices` | S&P 500, NASDAQ, KOSPI, BTC |
+| GET | `/api/market/overview` | 글로벌 시장 개요 |
+| GET | `/api/market/overview/{ticker}` | 자산유형별 개요 (Equity/ETF/Commodity 자동분기) |
+| GET | `/api/market/sectors` | 섹터 히트맵 데이터 |
| GET | `/api/market/sector/{ticker}` | 섹터, 산업, 시총, PE, 베타, 52주 |
| GET | `/api/market/health/{ticker}` | DuPont, Altman Z, Red Flags |
-| GET | `/api/market/price/{ticker}` | 현재가, 변동률 |
-| GET | `/api/market/indices` | S&P 500, NASDAQ, KOSPI, BTC |
+| GET | `/api/market/quote/{ticker}` | 현재가, 변동률 (빠른 시세) |
+| GET | `/api/market/trend/{ticker}` | 5년 재무 트렌드 |
+| GET | `/api/market/peers/{ticker}` | 동종업계 밸류에이션 멀티플 |
+| GET | `/api/market/comps` | 비교기업 분석 |
+| GET | `/api/market/piotroski/{ticker}` | Piotroski F-Score |
+| GET | `/api/market/sankey/{ticker}` | 손익 Sankey 데이터 |
+| GET | `/api/market/radar/{ticker}` | 레이더 차트 지표 |
+| GET | `/api/market/etf/{ticker}/holdings` | ETF 보유종목 |
+| GET | `/api/market/commodity/{ticker}/seasonal` | 원자재 월별 계절성 |
+| GET | `/api/market/commodity/{ticker}/correlations` | 원자재 상관관계 |
### 5.2 Financials (`/api/financials`)
| Method | Path | 설명 |
|--------|------|------|
-| GET | `/api/financials/{ticker}` | 손익계산서 (yfinance → yahooquery 폴백) |
-| GET | `/api/financials/balance/{ticker}` | 대차대조표 |
-| GET | `/api/financials/cashflow/{ticker}` | 현금흐름표 |
+| GET | `/api/financials/{ticker}/statements` | IS + BS + CF 통합 (yfinance → yahooquery 폴백) |
+| GET | `/api/financials/{ticker}/highlights` | 핵심 재무 요약 (매출, 마진, ROE, D/E, OCF) |
+| GET | `/api/financials/{ticker}/kpi-history` | 분기 KPI 시계열 (매출성장, 마진, ROE, FCF) |
+| GET | `/api/financials/{ticker}/ratios` | 밸류에이션·재무 비율 |
### 5.3 Valuation (`/api/valuation`)
| Method | Path | 설명 |
|--------|------|------|
-| POST | `/api/valuation/dcf` | 10Y 2-Stage DCF |
+| GET | `/api/valuation/dcf-inputs/{ticker}` | DCF 입력 자동채움 |
+| GET | `/api/valuation/smart-defaults/{ticker}` | 스마트 DCF 기본값 |
+| POST | `/api/valuation/dcf` | 3-시나리오 DCF |
| POST | `/api/valuation/sensitivity` | WACC × Terminal Growth 매트릭스 |
| POST | `/api/valuation/monte-carlo` | 5000회 시뮬레이션 + 히스토그램 |
| POST | `/api/valuation/tornado` | 변수별 민감도 순위 |
| POST | `/api/valuation/reverse-dcf` | 시장 내재 성장률 (scipy brentq) |
+| GET | `/api/valuation/consensus/{ticker}` | 애널리스트 컨센서스 |
### 5.4 Technical (`/api/technical`)
| Method | Path | 설명 |
|--------|------|------|
-| GET | `/api/technical/{ticker}` | RSI, MACD, Bollinger, MA, ADX, Ichimoku |
-| GET | `/api/technical/{ticker}/chart` | OHLCV 캔들 데이터 |
+| GET | `/api/technical/{ticker}/indicators` | RSI, SMA, EMA, MACD, BB, ATR |
+| GET | `/api/technical/{ticker}/chart-data` | OHLCV 캔들 데이터 |
+| GET | `/api/technical/{ticker}/fibonacci` | 피보나치 되돌림 레벨 |
+| GET | `/api/technical/{ticker}/ichimoku` | 일목균형표 클라우드 |
### 5.5 Earnings (`/api/earnings`)
| Method | Path | 설명 |
@@ -262,49 +346,103 @@ fontFamily: {
| GET | `/api/earnings/{ticker}/history` | EPS Beat/Miss 이력 |
| GET | `/api/earnings/{ticker}/calendar` | 다음 실적 발표일 |
| GET | `/api/earnings/{ticker}/quarterly` | 분기별 매출/순이익 |
+| GET | `/api/earnings/{ticker}/transcript` | 어닝콜 트랜스크립트 (FMP 키 필요) |
-### 5.6 Insider (`/api/insider`)
+### 5.6 Research (`/api/research`)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/research/dashboard/{ticker}` | 퀀트 대시보드 (F-Score/DuPont/Sankey/Waterfall/Anomaly) |
+
+### 5.7 FMP (`/api/fmp`, 선택)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/fmp/key-metrics/{ticker}` | 히스토리컬 key metrics (키 없으면 Yahoo 스냅샷) |
+| GET | `/api/fmp/ratios/{ticker}` | 히스토리컬 ratios (키 없으면 Yahoo 스냅샷) |
+
+### 5.8 Macro (`/api/macro`)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/macro/quadrant` | 글로벌 성장 vs 인플레 Z-score 사분면 |
+| GET | `/api/macro/yield-fx` | US10Y 스프레드 vs FX (usdjpy\|eurusd\|usdkrw) |
+| GET | `/api/macro/smart-money` | Copper/Gold ratio + RORO 복합지수 |
+| GET | `/api/macro/fred/{series_id}` | FRED 시계열 (공개 CSV) |
+| GET | `/api/macro/oecd/mei` | OECD MEI (빈 배열 — API 변경 대비) |
+| GET | `/api/macro/oecd/cli` | OECD CLI 스냅샷 (DBnomics) |
+| GET | `/api/macro/snapshot` | 매크로 사이클 히트맵 (국가, 자산, 밸류에이션) |
+| GET | `/api/macro/korea` | 한국 경제 지표 (ECOS or yfinance 폴백) |
+| GET | `/api/macro/economic-calendar` | 경제 캘린더 (스크래핑) |
+| GET | `/api/macro/ecos` | ECOS 직접 호출 (`ECOS_API_KEY`) |
+| GET | `/api/macro/calendar` | 경제 캘린더 — FMP (`FMP_API_KEY`) |
+
+### 5.9 DART (`/api/dart`, 선택)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/dart/search?q=` | 상장사 이름 검색 (`DART_API_KEY`) |
+| GET | `/api/dart/sections/{ticker}` | 최신 사업보고서 → SEC 유사 5섹션 + HTML (`.KS` / `.KQ`) |
+
+### 5.10 EDINET (`/api/edinet`, 선택)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/edinet/links/{ticker}` | EDINET 포털 링크 (키 없이 사용, `7203.T`) |
+| GET | `/api/edinet/sections/{ticker}` | 有価証券報告書 섹션 (`EDINET_SUBSCRIPTION_KEY` 없으면 링크만) |
+
+### 5.11 SEC EDGAR (`/api/edgar`)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/edgar/sections/{ticker}` | 10-K 섹션별 텍스트 (1A, 3, 7, 8, 9A) |
+| GET | `/api/edgar/item7/{ticker}` | Item 7 MD&A 텍스트만 |
+| GET | `/api/edgar/compare/{ticker}` | 최신 vs 3년전 Item 7 비교 |
+
+### 5.12 Insider (`/api/insider`)
| Method | Path | 설명 |
|--------|------|------|
| GET | `/api/insider/{ticker}` | 최근 내부자 거래 |
| GET | `/api/insider/{ticker}/holders` | 기관투자자 보유 현황 |
-### 5.7 News (`/api/news`)
+### 5.13 News (`/api/news`)
| Method | Path | 설명 |
|--------|------|------|
-| GET | `/api/news/{ticker}` | Finviz + Google News RSS |
+| GET | `/api/news/{ticker}` | Finviz(스크랩) + Google RSS + Yahoo Finance RSS |
+| GET | `/api/news/{ticker}/sentiment` | 뉴스 감성 분석 |
-### 5.8 SEC EDGAR (`/api/edgar`)
+### 5.14 Screener (`/api/screener`)
| Method | Path | 설명 |
|--------|------|------|
-| POST | `/api/edgar/download` | 10-K 다운로드 (sec-edgar-downloader) |
-| GET | `/api/edgar/sections/{ticker}` | 10-K 섹션별 텍스트 (1A, 3, 7, 8, 9A) |
+| POST | `/api/screener/search` | 종목 스크리너 (PE, 섹터, 배당 필터) |
+| POST | `/api/screener/backtest` | 전략 백테스트 (SMA/RSI/Buy&Hold) |
-### 5.9 기타
+### 5.15 Markets (`/api/markets`)
+| Method | Path | 설명 |
+|--------|------|------|
+| GET | `/api/markets/heatmap/{index_name}` | 지수 구성종목 히트맵 (S&P/NASDAQ/KOSPI/FTSE) |
+
+### 5.16 기타
| Prefix | 설명 |
|--------|------|
-| `/api/analysis` | Gemini AI 분석 |
-| `/api/chat` | AI Copilot 대화 |
-| `/api/crypto` | 암호화폐 (Bithumb + Binance) |
+| `/api/analysis` | Gemini AI 분석 (strategy/risks/mda/forensic/financials) |
+| `/api/chat` | AI Copilot (stream/complete/suggested/configure) |
+| `/api/crypto` | 암호화폐 시세 |
| `/api/fx` | 환율 |
-| `/api/estimates` | 애널리스트 추정치 |
-| `/api/portfolio` | 포트폴리오 CRUD + Risk Metrics |
+| `/api/estimates` | 애널리스트 추정치 (consensus/history/growth) |
+| `/api/portfolio` | 포트폴리오 CRUD + Risk + OCR + Screenshot |
---
-## 6. Frontend Pages (10개)
+## 6. Frontend Pages (전체 12개)
| 경로 | 파일 | 핵심 기능 |
|------|------|----------|
-| `/` | `page.tsx` | Overview — 섹터/산업, 시총/PE/베타, Altman Z-Score, DuPont 분해 |
-| `/research` | `research/page.tsx` | 10-K AI 분석 — MD&A + Risk Factors (Gemini) |
-| `/valuation` | `valuation/page.tsx` | **5-Tab**: DCF, Sensitivity Matrix (WACC×TG), Monte Carlo (히스토그램), Tornado, Reverse DCF |
-| `/technical` | `technical/page.tsx` | TradingView 캔들차트 (lightweight-charts), RSI/MACD/ATR 카드, 이동평균 테이블, Bollinger, Fibonacci |
-| `/markets` | `markets/page.tsx` | 재무제표 테이블 — Revenue→EBITDA, YoY Growth 뱃지(초록/빨강), Margin % 행 |
+| `/` | `page.tsx` | **Multi-Asset Overview** — 티커 자동감지 → Equity(섹터/DuPont/Altman Z/KPI/Peer)/ETF(보유종목/섹터비중)/Commodity(계절성/상관) |
+| `/research` | `research/page.tsx` | **리서치 그리드** — F-Score 이력, DuPont Tree, Sankey(손익흐름), Waterfall(영업이익), YoY 이상치+Gemini 설명 |
+| `/valuation` | `valuation/page.tsx` | **5-Tab**: DCF(3시나리오), Sensitivity Matrix(WACC×TG), Monte Carlo(히스토그램), Tornado, Reverse DCF |
+| `/technical` | `technical/page.tsx` | TradingView 캔들(lightweight-charts), RSI/MACD/ATR 카드, 이동평균, Bollinger, Fibonacci, Ichimoku |
+| `/markets` | `markets/page.tsx` | 재무제표 테이블(YoY Growth/Margin) + **섹터 히트맵**(S&P/NASDAQ/KOSPI/FTSE) |
+| `/macro` | `macro/page.tsx` | **5탭**(FRED/Cycle Heatmap/OECD CLI/Korea/Calendar) + **Quadrant**(성장vs인플레) + **YieldFX** + **SmartMoney**(Copper/Gold+RORO) |
| `/earnings` | `earnings/page.tsx` | 다음 실적일, EPS Beat/Miss 바차트, 분기 매출/순이익 |
| `/news` | `news/page.tsx` | Split-view — 좌측 기사 리스트(340px) + 우측 iframe 원문 보기 |
-| `/portfolio` | `portfolio/page.tsx` | 포지션 관리 + Risk Metrics (VaR, Sharpe, MDD) |
-| `/filings` | `filings/page.tsx` | SEC 10-K 원문 — 5개 섹션 탭 (Risk, MD&A, Financials, Legal, Controls) + AI Summary |
+| `/screener` | `screener/page.tsx` | **종목 스크리너**(PE/섹터/배당 필터) + **전략 백테스트**(SMA/RSI/Buy&Hold, 캔들차트 시각화) |
+| `/portfolio` | `portfolio/page.tsx` | 포지션 CRUD + Risk Metrics(VaR/Sharpe/MDD) + OCR 스크린샷 |
+| `/filings` | `filings/page.tsx` | **관할권 자동분기** — 티커 접미사로 SEC/DART(`.KS`/`.KQ`)/EDINET(`.T`), 5탭 + AI Summary |
| `/settings` | `settings/page.tsx` | Gemini API Key, SEC Email 설정 |
---
@@ -431,9 +569,11 @@ pandas>=2.0.0 lxml>=4.9.0
python-dotenv>=1.0.0 yfinance>=0.2.40
yahooquery>=2.2.0 sec-edgar-downloader>=5.0.0
feedparser>=6.0.0 ta>=0.11.0
-numpy scipy
+dart-fss>=0.4.0 numpy>=1.20.0
+scipy>=1.10.0 dbnomics>=1.2.0
aiosqlite>=0.20.0 asyncpg>=0.30.0
-pillow>=10.0.0
+pillow>=10.0.0 httpx>=0.27.0
+pytest>=8.0.0
```
### Node.js (`apps/web/package.json`)
@@ -441,6 +581,8 @@ pillow>=10.0.0
next: 14.2.35 react: ^18
lightweight-charts: ^5.1.0
tailwindcss: ^3.4.1 typescript: ^5
+@nivo/sankey: ^0.99.0 @nivo/bar: ^0.99.0
+recharts: ^2.15.4
```
---
@@ -451,7 +593,10 @@ GOOGLE_API_KEY= # Gemini API
SEC_EDGAR_EMAIL= # SEC 정책 필수 (10-K 다운로드용)
DATABASE_URL= # PostgreSQL (없으면 SQLite 자동)
NEWS_API_KEY= # 선택
-DART_API_KEY= # 한국 공시 (선택)
+FMP_API_KEY= # Financial Modeling Prep (선택 — 비율·트랜스크립트·캘린더)
+ECOS_API_KEY= # 한국은행 ECOS (선택)
+DART_API_KEY= # 금융감독원 Open DART (선택 — DART 사업보고서)
+EDINET_SUBSCRIPTION_KEY= # 일본 금융청 EDINET API v2 (선택 — 有価証券報告書)
```
---
@@ -470,16 +615,24 @@ DART_API_KEY= # 한국 공시 (선택)
## 13. 미구현 기능 (TODO)
-- [ ] Widget-based 대시보드 (react-grid-layout) — 패키지 설치됨, 미구현
+- [ ] Widget-based 대시보드 (react-grid-layout) — 미구현, 패키지도 미설치
- [ ] Enhanced AI Copilot — 인용/추론 단계 표시
- [ ] Multi-LLM 시스템 (Gemini + Claude + OpenAI provider abstraction) — `ai/llm_router.py` 스캐폴딩만
-- [ ] Extended DuPont 5-Factor 분석
-- [ ] DART (한국 공시) / EDINET (일본 공시) 통합
-- [ ] 포트폴리오 스크린샷 OCR (Gemini Vision) — 서비스 존재, UI 미연결
+- [ ] Extended DuPont 5-Factor 분석 — 현재 3-Factor만
+- [x] DART 사업보고서 Filings 연동 (`/api/dart/sections/{ticker}`, `dart_filing_service`)
+- [x] EDINET 링크 + 선택적 본문 (`/api/edinet/sections|links`, `EDINET_SUBSCRIPTION_KEY`)
+- [x] Sankey 차트 (`research/SankeyWidget.tsx` + `@nivo/sankey`)
+- [x] Radar 차트 (`/api/market/radar/{ticker}` 엔드포인트)
+- [x] 종목 스크리너 + 전략 백테스트 (`/screener` 페이지)
+- [x] Multi-Asset Overview — Equity/ETF/Commodity 자동분기
+- [x] Macro 페이지 — FRED/Cycle/OECD/Korea/Calendar + Quadrant/YieldFX/SmartMoney
+- [x] Research 대시보드 — F-Score/DuPont Tree/Sankey/Waterfall/Anomaly 그리드
+- [x] 관할권 자동분기 Filings — SEC/DART/EDINET 티커 접미사 기반
+- [x] 포트폴리오 OCR 스크린샷 — `/api/portfolio/screenshot` 엔드포인트 + UI 연결
- [ ] ⌘K 글로벌 커맨드 팔레트
-- [ ] Sankey (자금흐름), Radar (재무건전성) 차트
+- [ ] Settings 페이지에 FMP/ECOS/DART/EDINET 키 설정 UI 추가
- [ ] GitHub README 자동 업데이트 워크플로우
---
-*마지막 수정: 2026-03-21*
+*마지막 수정: 2026-03-26*
diff --git a/atlas-terminal/requirements.txt b/atlas-terminal/requirements.txt
index d6b6d44..210d75b 100644
--- a/atlas-terminal/requirements.txt
+++ b/atlas-terminal/requirements.txt
@@ -19,3 +19,7 @@ asyncpg>=0.30.0
pytest>=8.0.0
httpx>=0.27.0
pillow>=10.0.0
+dart-fss>=0.4.0
+numpy>=1.20.0
+scipy>=1.10.0
+dbnomics>=1.2.0
diff --git a/atlas-terminal/server/main.py b/atlas-terminal/server/main.py
index 4a23bb5..1274815 100644
--- a/atlas-terminal/server/main.py
+++ b/atlas-terminal/server/main.py
@@ -44,7 +44,7 @@ app.add_middleware(
)
# --- Mount routers ---
-from server.routers import edgar, analysis, valuation, market_data, news, crypto, fx, portfolio, technical, financials, estimates, earnings, insider, screener, markets # noqa: E402
+from server.routers import edgar, analysis, valuation, market_data, news, crypto, fx, portfolio, technical, financials, estimates, earnings, insider, screener, markets, fmp, macro, dart, edinet, research, chat # noqa: E402
app.include_router(edgar.router, prefix="/api/edgar", tags=["SEC EDGAR"])
app.include_router(analysis.router, prefix="/api/analysis", tags=["AI Analysis"])
@@ -61,6 +61,12 @@ app.include_router(technical.router, prefix="/api/technical", tags=["Technical"]
app.include_router(earnings.router, prefix="/api/earnings", tags=["Earnings"])
app.include_router(insider.router, prefix="/api/insider", tags=["Insider Trading"])
app.include_router(screener.router, prefix="/api/screener", tags=["Screener"])
+app.include_router(fmp.router, prefix="/api/fmp", tags=["FMP"])
+app.include_router(macro.router, prefix="/api/macro", tags=["Macro"])
+app.include_router(dart.router, prefix="/api/dart", tags=["DART"])
+app.include_router(edinet.router, prefix="/api/edinet", tags=["EDINET"])
+app.include_router(research.router, prefix="/api/research", tags=["Research"])
+app.include_router(chat.router, prefix="/api/chat", tags=["Chat"])
@app.get("/health")
diff --git a/atlas-terminal/server/models/schemas.py b/atlas-terminal/server/models/schemas.py
index b607c8c..faeaca7 100644
--- a/atlas-terminal/server/models/schemas.py
+++ b/atlas-terminal/server/models/schemas.py
@@ -1,7 +1,7 @@
"""Pydantic request/response schemas for ATLAS Terminal API."""
from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
+from typing import Any, Dict, List, Literal, Optional
# ---------------------------------------------------------------------------
@@ -141,6 +141,108 @@ class PiotroskiResponse(BaseModel):
used_ttm: bool = False
+class FScoreYearPoint(BaseModel):
+ """Single fiscal year pass/fail for one Piotroski criterion."""
+ year: int
+ pass_flag: bool
+
+
+class FScoreCriterionSeries(BaseModel):
+ """Three-year (or shorter) history for one F-Score criterion."""
+ key: str
+ label: str
+ history: List[FScoreYearPoint] = Field(default_factory=list)
+
+
+class DuPontTreeNode(BaseModel):
+ """One node in the DuPont ROE tree."""
+ id: str
+ label: str
+ value: float
+ unit: str = "pct"
+ avg_5y: Optional[float] = None
+ vs_5y_avg_pct: Optional[float] = None
+ trend: str = "flat"
+
+
+class DuPontTreePayload(BaseModel):
+ """ROE root with NPM, asset turnover, equity multiplier children."""
+ root: DuPontTreeNode
+ npm: DuPontTreeNode
+ asset_turnover: DuPontTreeNode
+ equity_mult: DuPontTreeNode
+
+
+class SankeyNivoNode(BaseModel):
+ """Node for @nivo/sankey."""
+ id: str
+ label: Optional[str] = None
+
+
+class SankeyNivoLink(BaseModel):
+ """Directed link for @nivo/sankey."""
+ source: str
+ target: str
+ value: float
+
+
+class SankeyGraphPayload(BaseModel):
+ """Sankey graph in Nivo-friendly shape."""
+ nodes: List[SankeyNivoNode] = Field(default_factory=list)
+ links: List[SankeyNivoLink] = Field(default_factory=list)
+
+
+class WaterfallStep(BaseModel):
+ """One bar in operating-income bridge chart."""
+ id: str
+ label: str
+ value: float
+ cumulative: float
+ step_type: str = "relative"
+
+
+class FinancialAnomalyItem(BaseModel):
+ """YoY line-item spike/drop for UI chips."""
+ account_key: str
+ display_name: str
+ prior_value: Optional[float] = None
+ current_value: Optional[float] = None
+ change_pct: Optional[float] = None
+ direction: str = "up"
+
+
+class ResearchDashboardResponse(BaseModel):
+ """Full research deep-dive payload (quant only)."""
+ ticker: str
+ fscore_total: int = 0
+ fscore_criteria: List[FScoreCriterionSeries] = Field(default_factory=list)
+ dupont_tree: Optional[DuPontTreePayload] = None
+ sankey: SankeyGraphPayload = Field(default_factory=SankeyGraphPayload)
+ waterfall: List[WaterfallStep] = Field(default_factory=list)
+ anomalies: List[FinancialAnomalyItem] = Field(default_factory=list)
+ error: Optional[str] = None
+
+
+class AnomalyExplainRequest(BaseModel):
+ """Request Gemini to explain a flagged line item using filing text."""
+ ticker: str
+ api_key: str
+ sec_email: str = Field(default="", description="SEC fair-access email; else SEC_EDGAR_EMAIL env")
+ account_key: str = ""
+ display_name: str = ""
+ direction: str = "up"
+ magnitude_pct: float = 0.0
+ filing_focus: str = Field(default="10k_mda", description="10k_mda or risk")
+
+
+class AnomalyExplainResponse(BaseModel):
+ """Strict JSON-shaped explanation from LLM."""
+ summary: str = ""
+ likely_causes: List[str] = Field(default_factory=list)
+ citations: List[Dict[str, str]] = Field(default_factory=list)
+ confidence: str = "medium"
+
+
class SankeyData(BaseModel):
"""Income statement Sankey diagram data."""
labels: List[str] = []
@@ -231,13 +333,19 @@ class CryptoPrice(BaseModel):
class EdgarSectionsResponse(BaseModel):
- """Cached or downloaded 10-K section texts."""
+ """Cached or downloaded filing section texts (SEC, DART, or EDINET)."""
+ source: Literal["sec", "dart", "edinet"] = "sec"
+ configured: bool = True
+ message: Optional[str] = None
+ links: Optional[Dict[str, str]] = None
status: str = ""
item1a: str = ""
item3: str = ""
item7: str = ""
item8: str = ""
item9a: str = ""
+ # When ``include_html=true``: HTML fragment for native viewer
+ html: str = ""
class Item7Response(BaseModel):
diff --git a/atlas-terminal/server/routers/analysis.py b/atlas-terminal/server/routers/analysis.py
index a19ea32..e80bb7b 100644
--- a/atlas-terminal/server/routers/analysis.py
+++ b/atlas-terminal/server/routers/analysis.py
@@ -4,12 +4,15 @@ Direct Gemini API calls without depending on Streamlit app module.
import json
import logging
-from typing import Optional
+import os
+import re
+from typing import Any, Dict, List
from fastapi import APIRouter, HTTPException
-from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
+from server.models.schemas import AnomalyExplainRequest, AnomalyExplainResponse
+
logger = logging.getLogger(__name__)
router = APIRouter()
@@ -29,7 +32,12 @@ class SimpleQuestionRequest(BaseModel):
api_key: str = ""
-def _call_gemini(api_key: str, prompt: str, max_tokens: int = 4096) -> str:
+def _call_gemini(
+ api_key: str,
+ prompt: str,
+ max_tokens: int = 4096,
+ temperature: float = 0.7,
+) -> str:
"""Call Gemini API directly and return text response."""
import urllib.request
import urllib.error
@@ -38,7 +46,7 @@ def _call_gemini(api_key: str, prompt: str, max_tokens: int = 4096) -> str:
payload = json.dumps({
"contents": [{"parts": [{"text": prompt}]}],
- "generationConfig": {"maxOutputTokens": max_tokens, "temperature": 0.7}
+ "generationConfig": {"maxOutputTokens": max_tokens, "temperature": temperature},
}).encode("utf-8")
req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
@@ -59,6 +67,88 @@ def _call_gemini(api_key: str, prompt: str, max_tokens: int = 4096) -> str:
raise HTTPException(status_code=500, detail=f"Gemini call failed: {e}")
+def _build_anomaly_filing_context(
+ ticker: str,
+ email: str,
+ filing_focus: str,
+ display_name: str,
+ account_key: str,
+) -> str:
+ from server.services.sec_parser import get_10k_sections
+ from server.services.text_chunker import smart_chunk
+
+ sections, _ = get_10k_sections(ticker.upper(), email.strip())
+ focus = (filing_focus or "10k_mda").lower()
+ if focus == "risk":
+ raw = "\n\n".join(
+ p
+ for p in (
+ sections.get("item1a", ""),
+ sections.get("item9a", ""),
+ sections.get("item3", ""),
+ )
+ if p
+ )
+ else:
+ raw = sections.get("item7", "") or ""
+
+ if not raw.strip():
+ return ""
+
+ hint = f"{display_name or ''} {account_key or ''}".strip()
+ if hint:
+ tokens = [t.lower() for t in re.split(r"[\s_/]+", hint) if len(t) > 2]
+ if tokens:
+ paras = [p.strip() for p in re.split(r"\n\s*\n", raw) if p.strip()]
+ if not paras:
+ paras = [raw]
+ scored: List[tuple[int, str]] = []
+ for para in paras:
+ pl = para.lower()
+ score = sum(1 for t in tokens if t in pl)
+ scored.append((score, para))
+ scored.sort(key=lambda x: (-x[0], -len(x[1])))
+ priority = "\n\n".join(p for _, p in scored[:15])
+ if priority.strip():
+ raw = priority
+
+ return smart_chunk(raw, max_chars=14000)
+
+
+def _parse_llm_json_object(text: str) -> Dict[str, Any]:
+ s = (text or "").strip()
+ if s.startswith("```"):
+ s = re.sub(r"^```(?:json)?\s*", "", s, flags=re.IGNORECASE)
+ s = re.sub(r"\s*```\s*$", "", s)
+ return json.loads(s)
+
+
+def _anomaly_response_from_parsed(obj: Dict[str, Any]) -> AnomalyExplainResponse:
+ cites = obj.get("citations") or []
+ norm_cites: List[Dict[str, str]] = []
+ if isinstance(cites, list):
+ for c in cites:
+ if isinstance(c, dict):
+ norm_cites.append(
+ {
+ "excerpt": str(c.get("excerpt", ""))[:2000],
+ "context": str(c.get("context", ""))[:500],
+ }
+ )
+ causes = obj.get("likely_causes") or []
+ if not isinstance(causes, list):
+ causes = []
+ conf = str(obj.get("confidence", "medium")).lower()
+ if conf not in ("high", "medium", "low"):
+ conf = "medium"
+ return AnomalyExplainResponse(
+ summary=str(obj.get("summary", ""))[:8000],
+ likely_causes=[str(x) for x in causes][:20],
+ citations=norm_cites[:15],
+ confidence=conf,
+ )
+
+
def _get_financial_context(ticker: str) -> str:
"""Build financial context from yfinance for AI analysis."""
try:
@@ -200,3 +290,88 @@ async def extract_financials(req: AnalysisRequest):
context = _get_financial_context(req.ticker.upper())
result = _call_gemini(api_key, f"Summarize the key financial data for analysis:\n\n{context}")
return {"ticker": req.ticker.upper(), "financials": result}
+
+
+@router.post(
+ "/anomaly-explain",
+ response_model=AnomalyExplainResponse,
+ summary="Explain YoY anomaly from 10-K text (strict JSON)",
+)
+async def anomaly_explain(req: AnomalyExplainRequest):
+ """Use Item 7 / risk sections plus Gemini to explain a flagged line item."""
+ api_key = (req.api_key or "").strip()
+ if not api_key:
+ raise HTTPException(status_code=400, detail="Gemini API key required.")
+
+ email = (req.sec_email or os.getenv("SEC_EDGAR_EMAIL") or "").strip()
+ if not email:
+ raise HTTPException(
+ status_code=400,
+ detail="SEC fair-access email required (pass sec_email or set SEC_EDGAR_EMAIL).",
+ )
+
+ try:
+ ctx = _build_anomaly_filing_context(
+ req.ticker,
+ email,
+ req.filing_focus,
+ req.display_name,
+ req.account_key,
+ )
+ except Exception as exc:
+ logger.exception("anomaly-explain filing load failed")
+ raise HTTPException(
+ status_code=502,
+ detail=f"Could not load SEC filing text: {exc}",
+ ) from exc
+
+ if not ctx:
+ raise HTTPException(
+ status_code=404,
+ detail="No 10-K section text available for this ticker.",
+ )
+
+ mag = float(req.magnitude_pct or 0.0)
+ dir_lbl = "increase" if (req.direction or "").lower() == "up" else "decrease"
+ prompt = f"""You are a securities analyst. The user flagged a large year-over-year change in a financial statement line item (from automated screening — do not recompute numbers).
+
+Ticker: {req.ticker.upper()}
+Line item (account key): {req.account_key or "unknown"}
+Display name: {req.display_name or "unknown"}
+Direction: {dir_lbl} (approx. {mag:.1f}% YoY — context only).
+
+Below is excerpted SEC filing text. Infer plausible qualitative explanations.
+
+--- FILING EXCERPT ---
+{ctx}
+--- END EXCERPT ---
+
+Output rules:
+- Single JSON object only. No markdown, no code fences, no surrounding text.
+- Do not invent new numerical results.
+- Required JSON shape:
+{{
+ "summary": "2-4 sentences",
+ "likely_causes": ["short strings"],
+ "citations": [{{"excerpt": "quote from excerpt", "context": "Item 7 / Item 1A / etc."}}],
+ "confidence": "high" | "medium" | "low"
+}}
+"""
+
+ raw = ""
+ try:
+ raw = _call_gemini(api_key, prompt, max_tokens=2048, temperature=0.2)
+ parsed = _parse_llm_json_object(raw)
+ return _anomaly_response_from_parsed(parsed)
+ except json.JSONDecodeError:
+ return AnomalyExplainResponse(
+ summary="The model returned non-JSON; raw output is attached in citations.",
+ likely_causes=[],
+ citations=[{"excerpt": (raw or "")[:1500], "context": "raw model output"}],
+ confidence="low",
+ )
+ except HTTPException:
+ raise
+ except Exception as exc:
+ logger.exception("anomaly-explain Gemini failed")
+ raise HTTPException(status_code=500, detail=str(exc)) from exc
diff --git a/atlas-terminal/server/routers/dart.py b/atlas-terminal/server/routers/dart.py
new file mode 100644
index 0000000..e946735
--- /dev/null
+++ b/atlas-terminal/server/routers/dart.py
@@ -0,0 +1,72 @@
+"""DART Korea — company search (optional ``DART_API_KEY``) + 사업보고서 sections."""
+
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, HTTPException, Query
+
+from server.models.schemas import EdgarSectionsResponse
+from server.services.dart_fetcher import dart_is_configured, search_corporations
+from server.services.dart_filing_service import (
+ dart_filing_is_configured,
+ get_dart_sections,
+)
+
+router = APIRouter()
+
+
+@router.get("/search", summary="Search DART corporations by name")
+async def dart_search(
+ q: str = Query(..., min_length=1, description="Company name (KO/EN)"),
+ limit: int = Query(20, ge=1, le=50),
+) -> Dict[str, Any]:
+ if not dart_is_configured():
+ return {
+ "configured": False,
+ "message": "Set DART_API_KEY in the environment.",
+ "results": [],
+ }
+ rows: List[Dict[str, Any]] = search_corporations(q, limit=limit)
+ return {"configured": True, "query": q, "count": len(rows), "results": rows}
+
+
+@router.get(
+ "/sections/{ticker}",
+ response_model=EdgarSectionsResponse,
+ summary="Korean 사업보고서 sections (DART Open API)",
+)
+async def dart_sections(
+ ticker: str,
+ include_html: bool = Query(
+ False,
+ description="Include HTML fragment for in-app viewer",
+ ),
+):
+ """Download latest annual report (사업보고서) and map to SEC-like section keys."""
+ if not dart_filing_is_configured():
+ return EdgarSectionsResponse(
+ source="dart",
+ configured=False,
+ message="Set DART_API_KEY in the environment (Open DART).",
+ status="unconfigured",
+ )
+ try:
+ sections, status, html_frag, _rcept = get_dart_sections(ticker)
+ except ValueError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ except FileNotFoundError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=f"DART download failed: {exc}") from exc
+
+ html_payload = html_frag if include_html else ""
+ return EdgarSectionsResponse(
+ source="dart",
+ configured=True,
+ status=status,
+ item1a=sections.get("item1a", ""),
+ item3=sections.get("item3", ""),
+ item7=sections.get("item7", ""),
+ item8=sections.get("item8", ""),
+ item9a=sections.get("item9a", ""),
+ html=html_payload,
+ )
diff --git a/atlas-terminal/server/routers/earnings.py b/atlas-terminal/server/routers/earnings.py
index 1b5317e..3c72f57 100644
--- a/atlas-terminal/server/routers/earnings.py
+++ b/atlas-terminal/server/routers/earnings.py
@@ -1,8 +1,8 @@
-"""Earnings router -- earnings history, upcoming dates, and transcripts."""
+"""Earnings router -- earnings history, upcoming dates, and transcripts (FMP)."""
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Query
router = APIRouter()
@@ -67,6 +67,46 @@ async def earnings_calendar(ticker: str) -> Dict[str, Any]:
raise HTTPException(status_code=500, detail=f"Earnings calendar failed: {exc}") from exc
+@router.get("/{ticker}/transcript", summary="Earnings call transcript (FMP)")
+async def earnings_transcript(
+ ticker: str,
+ year: int = Query(..., ge=1990, le=2035),
+ quarter: int = Query(..., ge=1, le=4),
+) -> Dict[str, Any]:
+ """Return one quarter of earnings call text from FMP when ``FMP_API_KEY`` is set."""
+ from server.services.fmp_client import fetch_earning_call_transcript, fmp_is_configured
+
+ if not fmp_is_configured():
+ return {
+ "ticker": ticker.upper(),
+ "year": year,
+ "quarter": quarter,
+ "available": False,
+ "message": "Set FMP_API_KEY for earnings call transcripts.",
+ "content": None,
+ }
+ rows: Optional[List[Dict[str, Any]]] = await fetch_earning_call_transcript(
+ ticker, year, quarter
+ )
+ if not rows:
+ return {
+ "ticker": ticker.upper(),
+ "year": year,
+ "quarter": quarter,
+ "available": False,
+ "message": "No transcript returned (symbol/quarter or API limit).",
+ "content": None,
+ }
+ # FMP returns list of dicts with 'content' or similar
+ return {
+ "ticker": ticker.upper(),
+ "year": year,
+ "quarter": quarter,
+ "available": True,
+ "data": rows,
+ }
+
+
@router.get("/{ticker}/quarterly", summary="Quarterly earnings data")
async def quarterly_earnings(ticker: str) -> Dict[str, Any]:
try:
diff --git a/atlas-terminal/server/routers/edgar.py b/atlas-terminal/server/routers/edgar.py
index f5d707e..1ec79c0 100644
--- a/atlas-terminal/server/routers/edgar.py
+++ b/atlas-terminal/server/routers/edgar.py
@@ -19,15 +19,32 @@ router = APIRouter()
async def get_sections(
ticker: str,
email: str = Query(..., description="SEC EDGAR fair-access email"),
+ include_html: bool = Query(
+ False,
+ description="Include original HTML (with section anchors) for iframe viewing",
+ ),
):
"""Return cleaned Item 1A, 3, 7, 8, 9A texts for *ticker*.
If the sections are already cached locally the download is skipped.
+ When *include_html* is true, the response includes ``html`` (wrapped 10-K
+ slice with ``id=atlas-item7`` etc. for in-page scrolling).
"""
try:
- from server.services.sec_parser import get_10k_sections
+ from server.services.sec_parser import (
+ download_and_extract_all_items,
+ get_10k_sections,
+ load_10k_html_slice,
+ )
sections, status = get_10k_sections(ticker.upper(), email)
+ html_payload = ""
+ if include_html:
+ html_payload = load_10k_html_slice(ticker.upper()) or ""
+ if not html_payload:
+ sections = download_and_extract_all_items(ticker.upper(), email)
+ status = "downloaded"
+ html_payload = load_10k_html_slice(ticker.upper()) or ""
return EdgarSectionsResponse(
status=status,
item1a=sections.get("item1a", ""),
@@ -35,6 +52,7 @@ async def get_sections(
item7=sections.get("item7", ""),
item8=sections.get("item8", ""),
item9a=sections.get("item9a", ""),
+ html=html_payload,
)
except FileNotFoundError as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
diff --git a/atlas-terminal/server/routers/edinet.py b/atlas-terminal/server/routers/edinet.py
new file mode 100644
index 0000000..e0b96a5
--- /dev/null
+++ b/atlas-terminal/server/routers/edinet.py
@@ -0,0 +1,60 @@
+"""EDINET Japan — optional annual report (有価証券報告書) + link fallbacks."""
+
+from fastapi import APIRouter, HTTPException, Query
+
+from server.models.schemas import EdgarSectionsResponse
+from server.services.edinet_filing_service import (
+ edinet_is_configured,
+ get_edinet_links,
+ get_edinet_sections,
+)
+
+router = APIRouter()
+
+
+@router.get("/links/{ticker}", summary="EDINET portal links (no API key required)")
+async def edinet_links(ticker: str):
+ return get_edinet_links(ticker)
+
+
+@router.get(
+ "/sections/{ticker}",
+ response_model=EdgarSectionsResponse,
+ summary="Japanese 有価証券報告書 sections (EDINET API v2)",
+)
+async def edinet_sections(
+ ticker: str,
+ include_html: bool = Query(
+ False,
+ description="Include HTML fragment for in-app viewer",
+ ),
+):
+ try:
+ sections, status, html_frag, meta = get_edinet_sections(ticker)
+ except ValueError as exc:
+ raise HTTPException(status_code=422, detail=str(exc)) from exc
+ except FileNotFoundError as exc:
+ raise HTTPException(status_code=404, detail=str(exc)) from exc
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=f"EDINET failed: {exc}") from exc
+
+ links = meta.get("links") if isinstance(meta.get("links"), dict) else None
+ configured = bool(meta.get("configured", edinet_is_configured()))
+ message = None
+ if not configured:
+ message = "Set EDINET_SUBSCRIPTION_KEY for in-app download; links are provided below."
+
+ html_payload = html_frag if include_html else ""
+ return EdgarSectionsResponse(
+ source="edinet",
+ configured=configured,
+ message=message,
+ links=links,
+ status=status,
+ item1a=sections.get("item1a", ""),
+ item3=sections.get("item3", ""),
+ item7=sections.get("item7", ""),
+ item8=sections.get("item8", ""),
+ item9a=sections.get("item9a", ""),
+ html=html_payload,
+ )
diff --git a/atlas-terminal/server/routers/financials.py b/atlas-terminal/server/routers/financials.py
index 28ebb59..f453767 100644
--- a/atlas-terminal/server/routers/financials.py
+++ b/atlas-terminal/server/routers/financials.py
@@ -64,7 +64,8 @@ def _safe_get(info: Dict[str, Any], key: str) -> Optional[float]:
async def financial_statements(ticker: str) -> Dict[str, Any]:
"""Return income statement, balance sheet, and cash flow for *ticker*.
- Attempts yahooquery first for richer data, then falls back to yfinance.
+ Tries yfinance annual statements first, then yahooquery if empty
+ (see ``claude.md`` §2.3 — order differs from ``market_fetcher``).
Includes up to 5 annual periods with YoY growth rates.
"""
try:
@@ -195,6 +196,28 @@ async def financial_highlights(ticker: str) -> Dict[str, Any]:
}
+@router.get(
+ "/{ticker}/kpi-history",
+ summary="Quarterly KPI series for charts",
+)
+async def kpi_history(ticker: str) -> Dict[str, Any]:
+ """QoQ revenue growth, margins, ROE, FCF from quarterly statements (no LLM)."""
+ try:
+ from server.services.kpi_history_service import build_kpi_history
+
+ return build_kpi_history(ticker)
+ except Exception:
+ return {
+ "ticker": ticker.upper(),
+ "quarters": [],
+ "revenue_growth": [],
+ "operating_margin": [],
+ "net_margin": [],
+ "roe": [],
+ "fcf": [],
+ }
+
+
@router.get(
"/{ticker}/ratios",
summary="Valuation and financial ratios",
diff --git a/atlas-terminal/server/routers/fmp.py b/atlas-terminal/server/routers/fmp.py
new file mode 100644
index 0000000..8d7ae7a
--- /dev/null
+++ b/atlas-terminal/server/routers/fmp.py
@@ -0,0 +1,45 @@
+"""FMP-backed valuation ratios and key metrics (optional API key)."""
+
+from typing import Any, Dict
+
+from fastapi import APIRouter, Query
+
+from server.services import fmp_client
+
+router = APIRouter()
+
+
+@router.get(
+ "/key-metrics/{ticker}",
+ summary="Historical key metrics (FMP or Yahoo fallback)",
+)
+async def get_key_metrics(
+ ticker: str,
+ period: str = Query("annual", description="annual or quarter"),
+ limit: int = Query(10, ge=1, le=40),
+) -> Dict[str, Any]:
+ """Return FMP key-metrics time series when ``FMP_API_KEY`` is set; else Yahoo snapshot."""
+ sym = ticker.strip().upper()
+ rows = await fmp_client.fetch_key_metrics(sym, period=period, limit=limit)
+ if rows:
+ return {"ticker": sym, "source": "fmp", "period": period, "data": rows}
+ fb = await fmp_client.fallback_valuation_snapshot(sym)
+ return {"ticker": sym, "source": "fallback", "period": period, "data": [], "snapshot": fb}
+
+
+@router.get(
+ "/ratios/{ticker}",
+ summary="Historical financial ratios (FMP or Yahoo fallback)",
+)
+async def get_ratios(
+ ticker: str,
+ period: str = Query("annual", description="annual or quarter"),
+ limit: int = Query(10, ge=1, le=40),
+) -> Dict[str, Any]:
+ """Return FMP ratios time series when key is set; else Yahoo snapshot."""
+ sym = ticker.strip().upper()
+ rows = await fmp_client.fetch_ratios(sym, period=period, limit=limit)
+ if rows:
+ return {"ticker": sym, "source": "fmp", "period": period, "data": rows}
+ fb = await fmp_client.fallback_valuation_snapshot(sym)
+ return {"ticker": sym, "source": "fallback", "period": period, "data": [], "snapshot": fb}
diff --git a/atlas-terminal/server/routers/macro.py b/atlas-terminal/server/routers/macro.py
new file mode 100644
index 0000000..7b9ceea
--- /dev/null
+++ b/atlas-terminal/server/routers/macro.py
@@ -0,0 +1,158 @@
+"""Macro data: FRED, OECD (best effort), ECOS, economic calendar (FMP)."""
+
+import asyncio
+import os
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, Query
+
+from server.services import fmp_client
+from server.services import macro_fetcher
+from server.services.global_macro_quadrant import get_global_macro_quadrant
+from server.services.smart_money_service import get_smart_money_snapshot
+from server.services.yield_fx_service import get_yield_fx_pair
+
+router = APIRouter()
+
+
+@router.get("/quadrant", summary="Global growth vs inflation quadrant (Z-scores)")
+async def macro_quadrant() -> Dict[str, Any]:
+ try:
+ return await asyncio.to_thread(get_global_macro_quadrant)
+ except Exception as exc:
+ return {"updated_at": None, "points": [], "error": str(exc)}
+
+
+@router.get("/yield-fx", summary="US10Y spread vs FX (usdjpy|eurusd|usdkrw)")
+async def macro_yield_fx(
+ pair: str = Query("usdjpy", description="usdjpy, eurusd, or usdkrw"),
+) -> Dict[str, Any]:
+ try:
+ return await asyncio.to_thread(get_yield_fx_pair, pair)
+ except Exception as exc:
+ return {
+ "pair": pair,
+ "updated_at": None,
+ "series": [],
+ "error": str(exc),
+ }
+
+
+@router.get("/smart-money", summary="Copper/Gold + RORO composite")
+async def macro_smart_money() -> Dict[str, Any]:
+ try:
+ return await asyncio.to_thread(get_smart_money_snapshot)
+ except Exception as exc:
+ return {
+ "updated_at": None,
+ "roro_z": None,
+ "roro_label": None,
+ "copper_gold": [],
+ "components": {},
+ "error": str(exc),
+ }
+
+
+@router.get("/fred/{series_id}", summary="FRED time series (public CSV)")
+async def macro_fred(
+ series_id: str,
+ start: Optional[str] = Query(None, description="YYYY-MM-DD"),
+ end: Optional[str] = Query(None, description="YYYY-MM-DD"),
+) -> Dict[str, Any]:
+ rows = await asyncio.to_thread(
+ macro_fetcher.fetch_fred_series,
+ series_id,
+ start,
+ end,
+ )
+ return {"series": series_id.strip().upper(), "count": len(rows), "data": rows}
+
+
+@router.get("/oecd/mei", summary="OECD MEI (best effort)")
+async def macro_oecd_mei() -> Dict[str, Any]:
+ rows = await asyncio.to_thread(macro_fetcher.fetch_oecd_mei)
+ return {"count": len(rows), "data": rows}
+
+
+@router.get("/oecd/cli", summary="OECD CLI snapshot (DBnomics)")
+async def macro_oecd_cli() -> Dict[str, Any]:
+ from server.services.oecd_cycle import get_oecd_cli_snapshot
+
+ try:
+ return await asyncio.to_thread(get_oecd_cli_snapshot)
+ except Exception as exc:
+ return {"updated_at": None, "countries": [], "error": str(exc)}
+
+
+@router.get("/snapshot", summary="Macro cycle heatmap, countries, asset valuation")
+async def macro_snapshot() -> Dict[str, Any]:
+ from server.services.macro_cycle import get_macro_cycle_snapshot
+
+ try:
+ return await asyncio.to_thread(get_macro_cycle_snapshot)
+ except Exception as exc:
+ return {
+ "updated_at": None,
+ "cycle_score": 0.0,
+ "regime": "Unknown",
+ "cycle_heatmap": [],
+ "country_heatmap": [],
+ "asset_valuation": [],
+ "error": str(exc),
+ }
+
+
+@router.get("/korea", summary="Korea indicators (ECOS or yfinance fallback)")
+async def macro_korea(
+ api_key: Optional[str] = Query(None, description="ECOS API key (optional)"),
+) -> Dict[str, Any]:
+ from server.services.ecos_fetcher import get_korea_snapshot
+
+ key = (api_key or os.getenv("ECOS_API_KEY") or "").strip() or None
+ return await asyncio.to_thread(get_korea_snapshot, key)
+
+
+@router.get("/economic-calendar", summary="Economic calendar (scraped; no API key)")
+async def macro_economic_calendar(
+ days: int = Query(7, ge=1, le=30),
+) -> Dict[str, Any]:
+ from server.services.economic_calendar import get_economic_calendar
+
+ try:
+ return await asyncio.to_thread(get_economic_calendar, days)
+ except Exception as exc:
+ return {"events": [], "next_high_impact": None, "total": 0, "error": str(exc)}
+
+
+@router.get("/ecos", summary="Korea Bank ECOS (requires ECOS_API_KEY)")
+async def macro_ecos(
+ stat_code: str = Query(..., description="ECOS 통계표 코드"),
+ cycle: str = Query("M", description="D/W/M/Q/S/Y"),
+ start_ym: str = Query("201501"),
+ end_ym: Optional[str] = Query(None),
+) -> Dict[str, Any]:
+ rows = await asyncio.to_thread(
+ macro_fetcher.fetch_ecos_series,
+ stat_code,
+ cycle,
+ start_ym,
+ end_ym,
+ )
+ return {"stat_code": stat_code, "count": len(rows), "data": rows}
+
+
+@router.get("/calendar", summary="Economic calendar (FMP when key set)")
+async def macro_calendar(
+ date_from: str = Query(..., description="YYYY-MM-DD"),
+ date_to: str = Query(..., description="YYYY-MM-DD"),
+) -> Dict[str, Any]:
+ if not fmp_client.fmp_is_configured():
+ return {
+ "source": "none",
+ "data": [],
+ "message": "Set FMP_API_KEY for economic_calendar, or use FRED directly.",
+ }
+ rows = await fmp_client.fetch_economic_calendar(date_from, date_to)
+ if rows:
+ return {"source": "fmp", "count": len(rows), "data": rows}
+ return {"source": "fmp", "data": [], "message": "No rows (range or API limit)."}
diff --git a/atlas-terminal/server/routers/market_data.py b/atlas-terminal/server/routers/market_data.py
index 0fd3b94..b2050ec 100644
--- a/atlas-terminal/server/routers/market_data.py
+++ b/atlas-terminal/server/routers/market_data.py
@@ -195,6 +195,23 @@ async def financial_trend(ticker: str):
return {"years": [], "revenue": [], "net_income": [], "operating_margin": [], "fcf": []}
+@router.get("/peers/{ticker}", summary="Peer valuation multiples (sector bucket)")
+async def peer_valuation_multiples(ticker: str):
+ """P/E, P/B, P/S, EV/EBITDA vs. a small industry peer set (yfinance)."""
+ try:
+ from server.services.peer_comparison_service import build_peer_comparison
+
+ return build_peer_comparison(ticker)
+ except Exception:
+ return {
+ "ticker": ticker.upper(),
+ "sector": "—",
+ "industry": "—",
+ "averages": {"pe": None, "pb": None, "ps": None, "ev_ebitda": None},
+ "peers": [],
+ }
+
+
@router.get("/comps", summary="Industry comparable companies")
async def industry_comps(tickers: str = Query(..., description="Comma-separated tickers")):
try:
@@ -432,6 +449,28 @@ async def piotroski_score(ticker: str):
return {"total": 0, "details": {}, "score": 0}
+@router.get("/quote/{ticker}", summary="Quick quote: price and session change %")
+async def quick_quote(ticker: str):
+ """Used for news headline ticker mentions (day session move)."""
+ try:
+ import yfinance as yf
+
+ info = (yf.Ticker(ticker.upper()).info) or {}
+ ch = _safe_float(info.get("regularMarketChangePercent"))
+ if ch is None:
+ p = _safe_float(info.get("regularMarketPrice") or info.get("currentPrice"))
+ prev = _safe_float(info.get("regularMarketPreviousClose") or info.get("previousClose"))
+ if p is not None and prev and prev != 0:
+ ch = (p - prev) / prev * 100
+ return {
+ "ticker": ticker.upper(),
+ "current_price": _safe_float(info.get("regularMarketPrice") or info.get("currentPrice")),
+ "change_pct": round(ch, 2) if ch is not None else None,
+ }
+ except Exception:
+ return {"ticker": ticker.upper(), "current_price": None, "change_pct": None}
+
+
@router.get("/sankey/{ticker}", summary="Income statement Sankey data")
async def sankey_data(ticker: str):
try:
@@ -459,9 +498,15 @@ async def sankey_data(ticker: str):
{"name": "Tax & Other", "value": abs(tax_other)},
{"name": "Net Income", "value": ni},
]
- return {"nodes": nodes}
+ try:
+ from server.services.research_dashboard import sankey_nivo_for_ticker
+
+ nivo = sankey_nivo_for_ticker(ticker)
+ except Exception:
+ nivo = {"nodes": [], "links": []}
+ return {"nodes": nodes, "nivo": nivo}
except Exception:
- return {"nodes": []}
+ return {"nodes": [], "nivo": {"nodes": [], "links": []}}
@router.get("/radar/{ticker}", summary="Radar chart metrics")
diff --git a/atlas-terminal/server/routers/news.py b/atlas-terminal/server/routers/news.py
index 6158cf7..42323db 100644
--- a/atlas-terminal/server/routers/news.py
+++ b/atlas-terminal/server/routers/news.py
@@ -1,119 +1,25 @@
-"""News router -- aggregated financial news from Finviz and Google News RSS."""
+"""News router -- Finviz scrape + Google News RSS + Yahoo Finance RSS."""
from typing import List
from fastapi import APIRouter, HTTPException, Query
from server.models.schemas import NewsItem
+from server.services.news_aggregator import merge_news_for_router
router = APIRouter()
-def _fetch_finviz_news(ticker: str) -> List[dict]:
- """Scrape recent headlines from Finviz news table for *ticker*."""
- import requests
- from bs4 import BeautifulSoup
-
- url = f"https://finviz.com/quote.ashx?t={ticker.upper()}&ty=c&p=d&b=1"
- headers = {"User-Agent": "ATLAS-Terminal/1.0"}
- try:
- resp = requests.get(url, headers=headers, timeout=10)
- resp.raise_for_status()
- except Exception:
- return []
-
- soup = BeautifulSoup(resp.text, "html.parser")
- news_table = soup.find(id="news-table")
- if not news_table:
- return []
-
- items: List[dict] = []
- current_date = ""
- for row in news_table.find_all("tr"):
- cells = row.find_all("td")
- if len(cells) < 2:
- continue
- date_cell = cells[0].get_text(strip=True)
- if len(date_cell) > 8:
- # Contains date + time, e.g. "Mar-18-26 08:30AM"
- current_date = date_cell
- else:
- # Time only -- reuse last date
- current_date = current_date.split(" ")[0] + " " + date_cell if current_date else date_cell
-
- link_tag = cells[1].find("a")
- if not link_tag:
- continue
- title = link_tag.get_text(strip=True)
- href = link_tag.get("href", "")
- source_span = cells[1].find("span")
- source = source_span.get_text(strip=True) if source_span else ""
-
- items.append({
- "title": title,
- "source": source,
- "url": href,
- "published_at": current_date,
- "summary": "",
- })
- return items[:20]
-
-
-def _fetch_google_news_rss(ticker: str) -> List[dict]:
- """Fetch recent headlines from Google News RSS for *ticker*."""
- import requests
- from xml.etree import ElementTree
-
- url = f"https://news.google.com/rss/search?q={ticker.upper()}+stock&hl=en-US&gl=US&ceid=US:en"
- try:
- resp = requests.get(url, timeout=10)
- resp.raise_for_status()
- except Exception:
- return []
-
- items: List[dict] = []
- try:
- root = ElementTree.fromstring(resp.content)
- for item in root.iter("item"):
- title = (item.findtext("title") or "").strip()
- link = (item.findtext("link") or "").strip()
- pub_date = (item.findtext("pubDate") or "").strip()
- source_el = item.find("source")
- source = source_el.text.strip() if source_el is not None and source_el.text else ""
- items.append({
- "title": title,
- "source": source,
- "url": link,
- "published_at": pub_date,
- "summary": "",
- })
- except Exception:
- pass
- return items[:20]
-
-
@router.get(
"/{ticker}",
response_model=List[NewsItem],
- summary="Aggregated news (Finviz + Google News)",
+ summary="Aggregated news (Finviz + Google + Yahoo)",
)
async def get_news(ticker: str):
- """Return up to 40 recent news articles for *ticker*, merged from
- Finviz and Google News RSS feeds. Duplicates are removed by title.
- """
+ """Return recent articles: Finviz table, Google News RSS, Yahoo headline RSS."""
try:
- finviz = _fetch_finviz_news(ticker.upper())
- google = _fetch_google_news_rss(ticker.upper())
-
- seen_titles: set = set()
- merged: List[dict] = []
- for item in finviz + google:
- t = item.get("title", "").strip().lower()
- if t and t not in seen_titles:
- seen_titles.add(t)
- merged.append(item)
-
- return [NewsItem(**item) for item in merged[:40]]
+ merged = merge_news_for_router(ticker.upper(), max_articles=40)
+ return [NewsItem(**item) for item in merged]
except Exception as exc:
raise HTTPException(status_code=500, detail=f"News fetch failed: {exc}") from exc
@@ -126,25 +32,14 @@ async def ai_news_summary(
ticker: str,
api_key: str = Query("", description="Google Gemini API key (optional)"),
):
- """Fetch news and optionally generate an AI summary of the top headlines.
-
- If *api_key* is provided, Gemini produces a short executive summary.
- Otherwise, the raw headlines are returned.
- """
+ """Fetch merged news and optionally summarize with Gemini."""
try:
- finviz = _fetch_finviz_news(ticker.upper())
- google = _fetch_google_news_rss(ticker.upper())
-
- seen_titles: set = set()
+ all_items = merge_news_for_router(ticker.upper(), max_articles=30)
headlines: List[str] = []
- all_items: List[dict] = []
- for item in finviz + google:
- t = item.get("title", "").strip()
- tl = t.lower()
- if tl and tl not in seen_titles:
- seen_titles.add(tl)
- headlines.append(t)
- all_items.append(item)
+ for item in all_items:
+ title = (item.get("title") or "").strip()
+ if title:
+ headlines.append(title)
headlines = headlines[:20]
all_items = all_items[:20]
@@ -157,8 +52,7 @@ async def ai_news_summary(
"items": all_items,
}
- # AI summary via Gemini
- from app import get_gemini_model, _generate_with_retry # type: ignore[import-untyped]
+ from server.services.gemini_service import get_gemini_model, _generate_with_retry
model = get_gemini_model(api_key)
headline_text = "\n".join(f"- {h}" for h in headlines)
diff --git a/atlas-terminal/server/routers/research.py b/atlas-terminal/server/routers/research.py
new file mode 100644
index 0000000..3aa5f44
--- /dev/null
+++ b/atlas-terminal/server/routers/research.py
@@ -0,0 +1,15 @@
+"""Research deep-dive dashboard API."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from server.services.research_dashboard import build_research_dashboard
+
+router = APIRouter()
+
+
+@router.get("/dashboard/{ticker}", summary="F-Score history, DuPont tree, Sankey, waterfall, anomalies")
+async def research_dashboard(ticker: str):
+ """Quant-only payload for Research page widgets."""
+ return build_research_dashboard(ticker).model_dump()
diff --git a/atlas-terminal/server/routers/screener.py b/atlas-terminal/server/routers/screener.py
index c631f9a..3ed5113 100644
--- a/atlas-terminal/server/routers/screener.py
+++ b/atlas-terminal/server/routers/screener.py
@@ -29,6 +29,9 @@ async def backtest(body: dict):
strategy=body.get("strategy", "buy_and_hold"),
start_date=body.get("start_date", "2024-01-01"),
end_date=body.get("end_date", "2026-01-01"),
+ initial_capital=float(body.get("initial_capital", 10000.0)),
+ benchmark_ticker=str(body.get("benchmark_ticker") or "SPY"),
+ rebalance_months=body.get("rebalance_months"),
)
except Exception as e:
return {"error": str(e)}
diff --git a/atlas-terminal/server/services/backtester.py b/atlas-terminal/server/services/backtester.py
index cf2c24e..eb3a0b0 100644
--- a/atlas-terminal/server/services/backtester.py
+++ b/atlas-terminal/server/services/backtester.py
@@ -1,7 +1,114 @@
-"""Backtesting service for simple strategies."""
+"""Backtesting service for simple strategies.
+
+Uses **adjusted** close prices (``auto_adjust=True``) so splits/dividends do not
+distort returns. Survivorship bias is **not** removed — the ticker must exist
+today; historical universes require a separate constituent database.
+"""
from __future__ import annotations
+import asyncio
+from typing import Any, Dict, Optional
+
+
+def _months_between(a: Any, b: Any) -> int:
+ return (b.year - a.year) * 12 + (b.month - a.month)
+
+
+def _run_backtest_impl(
+ ticker: str,
+ strategy: str,
+ start_date: str,
+ end_date: str,
+ initial_capital: float = 10000.0,
+ benchmark_ticker: str = "SPY",
+ rebalance_months: Optional[int] = None,
+) -> Dict[str, Any]:
+ import yfinance as yf
+ import ta
+
+ sym = ticker.upper()
+ bm_sym = (benchmark_ticker or "SPY").upper()
+
+ df = yf.Ticker(sym).history(
+ start=start_date,
+ end=end_date,
+ auto_adjust=True,
+ )
+ if df is None or df.empty:
+ return {"error": "No price data"}
+
+ price = df["Close"]
+
+ if strategy == "sma_crossover":
+ df = df.copy()
+ df["sma50"] = ta.trend.sma_indicator(price, 50)
+ df["sma200"] = ta.trend.sma_indicator(price, 200)
+ df["signal"] = (df["sma50"] > df["sma200"]).astype(int)
+ elif strategy == "rsi_oversold":
+ df = df.copy()
+ df["rsi"] = ta.momentum.rsi(price, 14)
+ df["signal"] = 0
+ df.loc[df["rsi"] < 30, "signal"] = 1
+ df.loc[df["rsi"] > 70, "signal"] = 0
+ else:
+ df = df.copy()
+ df["signal"] = 1
+
+ if rebalance_months is not None and int(rebalance_months) >= 1:
+ months = int(rebalance_months)
+ raw = df["signal"].astype(float)
+ last_rebal = None
+ hold = 0.0
+ carried: list[float] = []
+ for dt in df.index:
+ if last_rebal is None or _months_between(last_rebal, dt) >= months:
+ last_rebal = dt
+ hold = float(raw.loc[dt])
+ carried.append(hold)
+ df["signal"] = carried
+
+ bm_hist = yf.Ticker(bm_sym).history(
+ start=start_date,
+ end=end_date,
+ auto_adjust=True,
+ )
+ if bm_hist is None or bm_hist.empty:
+ return {"error": f"No benchmark data for {bm_sym}"}
+
+ common = df.index.intersection(bm_hist.index)
+ if len(common) < 5:
+ return {"error": "Insufficient overlap between asset and benchmark history"}
+
+ df = df.loc[common]
+ price = df["Close"]
+ bm_close = bm_hist.loc[common, "Close"]
+
+ df["returns"] = price.pct_change().fillna(0)
+ bm_returns = bm_close.pct_change().fillna(0)
+
+ df["strategy_returns"] = (df["returns"] * df["signal"].shift(1)).fillna(0)
+ cumulative = (1 + df["strategy_returns"]).cumprod()
+ benchmark = (1 + bm_returns).cumprod()
+
+ return {
+ "ticker": sym,
+ "benchmark_ticker": bm_sym,
+ "total_return_pct": round((float(cumulative.iloc[-1]) - 1) * 100, 2),
+ "benchmark_return_pct": round((float(benchmark.iloc[-1]) - 1) * 100, 2),
+ "alpha": round((float(cumulative.iloc[-1]) - float(benchmark.iloc[-1])) * 100, 2),
+ "max_drawdown_pct": round(float(((cumulative / cumulative.cummax()) - 1).min()) * 100, 2),
+ "sharpe_ratio": round(
+ float(df["strategy_returns"].mean() / (df["strategy_returns"].std() + 1e-10) * (252**0.5)),
+ 2,
+ ),
+ "equity_curve": [float(x) for x in cumulative.tolist()],
+ "benchmark_curve": [float(x) for x in benchmark.tolist()],
+ "dates": df.index.strftime("%Y-%m-%d").tolist(),
+ "initial_capital": initial_capital,
+ "rebalance_months": rebalance_months,
+ }
+
async def run_backtest(
ticker: str,
@@ -9,39 +116,17 @@ async def run_backtest(
start_date: str,
end_date: str,
initial_capital: float = 10000.0,
+ benchmark_ticker: str = "SPY",
+ rebalance_months: Optional[int] = None,
) -> dict:
- """Run a basic backtest for selected strategy."""
- import yfinance as yf
- import ta
-
- df = yf.Ticker(ticker.upper()).history(start=start_date, end=end_date)
- if df is None or df.empty:
- return {"error": "No price data"}
-
- if strategy == "sma_crossover":
- df["sma50"] = ta.trend.sma_indicator(df["Close"], 50)
- df["sma200"] = ta.trend.sma_indicator(df["Close"], 200)
- df["signal"] = (df["sma50"] > df["sma200"]).astype(int)
- elif strategy == "rsi_oversold":
- df["rsi"] = ta.momentum.rsi(df["Close"], 14)
- df["signal"] = 0
- df.loc[df["rsi"] < 30, "signal"] = 1
- df.loc[df["rsi"] > 70, "signal"] = 0
- else:
- df["signal"] = 1
-
- df["returns"] = df["Close"].pct_change().fillna(0)
- df["strategy_returns"] = (df["returns"] * df["signal"].shift(1)).fillna(0)
- cumulative = (1 + df["strategy_returns"]).cumprod()
- benchmark = (1 + df["returns"]).cumprod()
-
- return {
- "total_return_pct": round((float(cumulative.iloc[-1]) - 1) * 100, 2),
- "benchmark_return_pct": round((float(benchmark.iloc[-1]) - 1) * 100, 2),
- "alpha": round((float(cumulative.iloc[-1]) - float(benchmark.iloc[-1])) * 100, 2),
- "max_drawdown_pct": round(float(((cumulative / cumulative.cummax()) - 1).min()) * 100, 2),
- "sharpe_ratio": round(float(df["strategy_returns"].mean() / (df["strategy_returns"].std() + 1e-10) * (252 ** 0.5)), 2),
- "equity_curve": [float(x) for x in cumulative.tolist()],
- "benchmark_curve": [float(x) for x in benchmark.tolist()],
- "dates": df.index.strftime("%Y-%m-%d").tolist(),
- }
+ """Run a basic backtest for selected strategy vs. a benchmark index."""
+ return await asyncio.to_thread(
+ _run_backtest_impl,
+ ticker,
+ strategy,
+ start_date,
+ end_date,
+ initial_capital,
+ benchmark_ticker,
+ rebalance_months,
+ )
diff --git a/atlas-terminal/server/services/cache.py b/atlas-terminal/server/services/cache.py
new file mode 100644
index 0000000..fa9c8b3
--- /dev/null
+++ b/atlas-terminal/server/services/cache.py
@@ -0,0 +1,40 @@
+"""Simple in-memory TTL cache for expensive macro data fetches."""
+
+from __future__ import annotations
+
+import time
+import threading
+from typing import Any, Callable, TypeVar
+
+_lock = threading.Lock()
+_store: dict[str, tuple[float, Any]] = {}
+
+F = TypeVar("F", bound=Callable)
+
+
+def cached(key: str, ttl_seconds: int = 3600):
+ """Decorator that caches a function result for *ttl_seconds*."""
+ def decorator(fn: Callable) -> Callable:
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
+ now = time.time()
+ with _lock:
+ if key in _store:
+ ts, val = _store[key]
+ if now - ts < ttl_seconds:
+ return val
+ result = fn(*args, **kwargs)
+ with _lock:
+ _store[key] = (now, result)
+ return result
+ return wrapper
+ return decorator
+
+
+def invalidate(key: str) -> None:
+ with _lock:
+ _store.pop(key, None)
+
+
+def invalidate_all() -> None:
+ with _lock:
+ _store.clear()
diff --git a/atlas-terminal/server/services/copilot_context.py b/atlas-terminal/server/services/copilot_context.py
deleted file mode 100644
index eb3923b..0000000
--- a/atlas-terminal/server/services/copilot_context.py
+++ /dev/null
@@ -1,24 +0,0 @@
-"""Build compact copilot context with asset-type aware fields."""
-
-from __future__ import annotations
-
-
-def build_copilot_context(asset_type: str, data: dict) -> str:
- parts: list[str] = []
- if asset_type == "etf":
- parts.append(f"[Asset Type] ETF — {data.get('category')}")
- parts.append(f"[ETF] AUM: {data.get('aum')}, Expense: {data.get('expense_ratio')}")
- r = data.get("returns") or {}
- parts.append(f"[Performance] YTD: {r.get('ytd')}%, 1Y: {r.get('1y')}%")
- elif asset_type == "commodity_future":
- parts.append(f"[Asset Type] Commodity Future — {data.get('name')}")
- parts.append(f"[Commodity] Open Interest: {data.get('open_interest')}")
- seasonal = data.get("seasonal_pattern") or {}
- if seasonal:
- best_month = max(seasonal, key=lambda k: seasonal[k])
- worst_month = min(seasonal, key=lambda k: seasonal[k])
- parts.append(f"[Seasonal] Best month: {best_month}, Worst: {worst_month}")
- else:
- parts.append("[Asset Type] Equity")
- parts.append(f"[Sector] {data.get('sector')}")
- return "\n".join(parts)
diff --git a/atlas-terminal/server/services/crypto_fetcher.py b/atlas-terminal/server/services/crypto_fetcher.py
deleted file mode 100644
index 90905fa..0000000
--- a/atlas-terminal/server/services/crypto_fetcher.py
+++ /dev/null
@@ -1,158 +0,0 @@
-"""Crypto price fetcher -- Bithumb (KRW) and Binance (USD) public APIs.
-
-Provides standalone fetcher functions that can be used by the crypto router
-or any other service that needs cryptocurrency price data.
-"""
-
-import time
-from typing import Any, Dict, List, Optional
-
-import requests
-
-# ---------------------------------------------------------------------------
-# Top 20 coins
-# ---------------------------------------------------------------------------
-
-TOP_20_COINS: List[str] = [
- "BTC", "ETH", "BNB", "XRP", "SOL", "ADA", "DOGE", "AVAX", "DOT", "MATIC",
- "LINK", "SHIB", "TRX", "UNI", "ATOM", "LTC", "ETC", "XLM", "NEAR", "APT",
-]
-
-# ---------------------------------------------------------------------------
-# In-memory cache
-# ---------------------------------------------------------------------------
-
-_cache: Dict[str, Any] = {}
-_cache_ts: Dict[str, float] = {}
-_CACHE_TTL = 30 # seconds
-
-
-def _get_cached(key: str) -> Optional[Any]:
- if key in _cache and (time.time() - _cache_ts.get(key, 0)) < _CACHE_TTL:
- return _cache[key]
- return None
-
-
-def _set_cached(key: str, value: Any) -> None:
- _cache[key] = value
- _cache_ts[key] = time.time()
-
-
-# ---------------------------------------------------------------------------
-# Bithumb (KRW)
-# ---------------------------------------------------------------------------
-
-def fetch_bithumb_all_krw(symbols: Optional[List[str]] = None) -> Dict[str, float]:
- """Fetch KRW prices from Bithumb ALL_KRW endpoint.
-
- Uses the bulk endpoint (https://api.bithumb.com/public/ticker/ALL_KRW)
- to avoid per-symbol rate limits.
-
- Parameters
- ----------
- symbols:
- Coin symbols to include. Defaults to TOP_20_COINS.
-
- Returns
- -------
- dict
- Mapping of symbol -> KRW price (float).
- """
- cached = _get_cached("bithumb_all_krw")
- if cached is not None:
- return cached
-
- symbols = symbols or TOP_20_COINS
- url = "https://api.bithumb.com/public/ticker/ALL_KRW"
- prices: Dict[str, float] = {}
- try:
- resp = requests.get(url, timeout=10)
- resp.raise_for_status()
- body = resp.json()
- if body.get("status") != "0000":
- return prices
- data = body.get("data", {})
- for sym in symbols:
- coin_data = data.get(sym.upper())
- if coin_data and isinstance(coin_data, dict):
- closing = coin_data.get("closing_price")
- if closing:
- prices[sym.upper()] = float(closing)
- except Exception:
- pass
-
- _set_cached("bithumb_all_krw", prices)
- return prices
-
-
-# ---------------------------------------------------------------------------
-# Binance (USD)
-# ---------------------------------------------------------------------------
-
-def fetch_binance_prices(symbols: Optional[List[str]] = None) -> Dict[str, float]:
- """Fetch USD prices from Binance ticker/price endpoint.
-
- Parameters
- ----------
- symbols:
- Coin symbols to include. Defaults to TOP_20_COINS.
-
- Returns
- -------
- dict
- Mapping of symbol -> USD price (float).
- """
- cached = _get_cached("binance_prices")
- if cached is not None:
- return cached
-
- symbols = symbols or TOP_20_COINS
- url = "https://api.binance.com/api/v3/ticker/price"
- prices: Dict[str, float] = {}
- try:
- resp = requests.get(url, timeout=10)
- resp.raise_for_status()
- data = resp.json()
- lookup = {item["symbol"]: float(item["price"]) for item in data}
- for sym in symbols:
- key = f"{sym.upper()}USDT"
- if key in lookup:
- prices[sym.upper()] = lookup[key]
- except Exception:
- pass
-
- _set_cached("binance_prices", prices)
- return prices
-
-
-# ---------------------------------------------------------------------------
-# Combined
-# ---------------------------------------------------------------------------
-
-def fetch_top20_prices(
- symbols: Optional[List[str]] = None,
-) -> List[Dict[str, Any]]:
- """Return top-20 crypto prices with both KRW and USD.
-
- Each entry contains:
- - symbol: str
- - price_usd: float | None
- - price_krw: float | None
-
- Parameters
- ----------
- symbols:
- Override default TOP_20_COINS list.
- """
- symbols = symbols or TOP_20_COINS
- usd = fetch_binance_prices(symbols)
- krw = fetch_bithumb_all_krw(symbols)
-
- results: List[Dict[str, Any]] = []
- for sym in symbols:
- results.append({
- "symbol": sym.upper(),
- "price_usd": usd.get(sym.upper()),
- "price_krw": krw.get(sym.upper()),
- })
- return results
diff --git a/atlas-terminal/server/services/dart_fetcher.py b/atlas-terminal/server/services/dart_fetcher.py
new file mode 100644
index 0000000..60237f3
--- /dev/null
+++ b/atlas-terminal/server/services/dart_fetcher.py
@@ -0,0 +1,50 @@
+"""DART (Korea disclosure) helpers via dart-fss (requires ``DART_API_KEY``)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List
+
+
+def dart_is_configured() -> bool:
+ return bool((os.getenv("DART_API_KEY") or "").strip())
+
+
+def search_corporations(query: str, limit: int = 20) -> List[Dict[str, Any]]:
+ """Search listed companies by Korean/English name (best effort)."""
+ key = (os.getenv("DART_API_KEY") or "").strip()
+ q = (query or "").strip()
+ if not key or not q:
+ return []
+
+ try:
+ import dart_fss as dart # noqa: WPS433
+ except ImportError:
+ return []
+
+ try:
+ dart.set_api_key(key)
+ corp_list = dart.get_corp_list()
+ found = corp_list.find_by_corp_name(q, exactly=False)
+ except Exception:
+ return []
+
+ if found is None:
+ return []
+
+ out: List[Dict[str, Any]] = []
+ for item in list(found)[:limit]:
+ row: Dict[str, Any] = {}
+ for attr in (
+ "corp_name",
+ "corp_eng_name",
+ "corp_code",
+ "stock_code",
+ "modify_date",
+ ):
+ if hasattr(item, attr):
+ row[attr] = getattr(item, attr)
+ if not row:
+ row["repr"] = repr(item)
+ out.append(row)
+ return out
diff --git a/atlas-terminal/server/services/dart_filing_service.py b/atlas-terminal/server/services/dart_filing_service.py
new file mode 100644
index 0000000..a2f03fa
--- /dev/null
+++ b/atlas-terminal/server/services/dart_filing_service.py
@@ -0,0 +1,312 @@
+"""DART 사업보고서 다운로드·섹션 매핑 (Open DART API + dart-fss)."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import zipfile
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from bs4 import BeautifulSoup
+
+from server.utils.ticker_utils import korean_stock_code_from_ticker
+
+_DATA_DIR: Path = Path(__file__).resolve().parents[3] / "data"
+
+# 사업보고서 (연)
+_PBLNTF_DETAIL_ANNUAL = "A001"
+
+
+def _dart_data_dir() -> Path:
+ _DATA_DIR.mkdir(parents=True, exist_ok=True)
+ return _DATA_DIR
+
+
+def _clean_korean_text(raw: str) -> str:
+ """Preserve Hangul; strip tags and collapse whitespace (no ASCII-only strip)."""
+ if not raw or not raw.strip():
+ return ""
+ try:
+ soup = BeautifulSoup(raw, "lxml")
+ for tag in soup.find_all(["script", "style"]):
+ tag.decompose()
+ text = soup.get_text(separator="\n")
+ except Exception:
+ text = re.sub(r"<[^>]+>", "\n", raw)
+ lines = [ln.strip() for ln in text.splitlines()]
+ lines = [ln for ln in lines if ln]
+ out = "\n".join(lines)
+ out = re.sub(r"\n{3,}", "\n\n", out)
+ return out.strip()
+
+
+def _cache_paths(stock_code: str) -> Tuple[Path, Path]:
+ base = _dart_data_dir()
+ return (
+ base / f"{stock_code}_dart_latest.json",
+ base / f"{stock_code}_dart_slice.html",
+ )
+
+
+def _extract_sections_from_plain(full: str) -> Dict[str, str]:
+ """Map Korean annual report prose into SEC-like keys (best effort)."""
+ text = full
+ if len(text) < 200:
+ return {
+ "item1a": "",
+ "item3": "",
+ "item7": text,
+ "item8": "",
+ "item9a": "",
+ }
+
+ def _slice_between(patterns_start: List[str], end_markers: List[re.Pattern]) -> str:
+ start_idx = -1
+ for p in patterns_start:
+ m = re.search(p, text, re.IGNORECASE | re.MULTILINE)
+ if m:
+ start_idx = m.start()
+ break
+ if start_idx < 0:
+ return ""
+ rest = text[start_idx:]
+ end_idx = len(rest)
+ for em in end_markers:
+ m2 = em.search(rest[1:])
+ if m2:
+ end_idx = min(end_idx, m2.start() + 1)
+ return rest[:end_idx].strip()
+
+ # End markers for major sections (next Roman section or 제N장)
+ next_section = re.compile(
+ r"(?=\n\s*(?:IV\.|III\.|II\.|Ⅳ\.|Ⅲ\.|Ⅱ\.|제\s*[0-9]+\s*부|제\s*[0-9]+\s*장))",
+ re.MULTILINE,
+ )
+
+ item1a = _slice_between(
+ [r"II\.\s*투자위험", r"투자위험요소", r"투자\s*위험"],
+ [next_section, re.compile(r"\n\s*III\.", re.MULTILINE)],
+ )
+ item7 = _slice_between(
+ [
+ r"경영자의\s*분석\s*의견",
+ r"II\.\s*사업의\s*내용",
+ r"사업의\s*내용",
+ ],
+ [next_section, re.compile(r"\n\s*III\.\s*재무", re.MULTILINE)],
+ )
+ if not item7:
+ item7 = _slice_between(
+ [r"II\.\s*사업의\s*내용"],
+ [next_section],
+ )
+
+ item8 = _slice_between(
+ [r"III\.\s*재무에\s*관한\s*사항", r"재무제표\s*등", r"연\s*결\s*재무제표"],
+ [next_section, re.compile(r"\n\s*IV\.", re.MULTILINE)],
+ )
+
+ item3 = _slice_between(
+ [r"법적\s*소송", r"소송", r"주요\s*사건", r"중요한\s*소송"],
+ [next_section],
+ )
+ item9a = _slice_between(
+ [r"내부\s*통제", r"내부회계관리제도", r"대표이사의\s*평가"],
+ [next_section],
+ )
+
+ if not any([item1a, item7, item8, item3, item9a]):
+ half = min(120_000, len(text))
+ item7 = text[:half]
+
+ return {
+ "item1a": item1a[:80_000] if item1a else "",
+ "item3": item3[:40_000] if item3 else "",
+ "item7": item7[:120_000] if item7 else text[:120_000],
+ "item8": item8[:200_000] if item8 else "",
+ "item9a": item9a[:40_000] if item9a else "",
+ }
+
+
+def _read_zip_text(zip_path: Path) -> str:
+ """Concatenate text from XML/HTML inside DART document zip."""
+ chunks: List[str] = []
+ try:
+ with zipfile.ZipFile(zip_path, "r") as zf:
+ names = zf.namelist()
+ # Prefer main document XML / HTM
+ ordered = sorted(
+ names,
+ key=lambda n: (
+ 0 if n.lower().endswith((".xml", ".htm", ".html")) else 1,
+ -len(n),
+ ),
+ )
+ for name in ordered[:50]:
+ if not name.lower().endswith((".xml", ".htm", ".html")):
+ continue
+ try:
+ data = zf.read(name)
+ encodings = ("utf-8", "cp949", "euc-kr", "latin-1")
+ decoded = ""
+ for enc in encodings:
+ try:
+ decoded = data.decode(enc)
+ break
+ except Exception:
+ continue
+ if decoded:
+ chunks.append(_clean_korean_text(decoded))
+ except Exception:
+ continue
+ except zipfile.BadZipFile:
+ raw = zip_path.read_bytes()
+ for enc in ("utf-8", "cp949", "euc-kr"):
+ try:
+ chunks.append(_clean_korean_text(raw.decode(enc)))
+ break
+ except Exception:
+ continue
+ combined = "\n\n".join(c for c in chunks if c)
+ return combined if combined else ""
+
+
+def _load_xml_or_raw(downloaded_path: Path) -> str:
+ p = downloaded_path
+ if p.suffix.lower() == ".zip" or zipfile.is_zipfile(p):
+ return _read_zip_text(p)
+ if p.suffix.lower() in (".xml", ".htm", ".html"):
+ raw = p.read_text(encoding="utf-8", errors="replace")
+ return _clean_korean_text(raw)
+ # Try zip anyway
+ try:
+ return _read_zip_text(p)
+ except Exception:
+ raw = p.read_bytes()
+ return _clean_korean_text(raw.decode("utf-8", errors="replace"))
+
+
+def _xml_escape(s: str) -> str:
+ return (
+ (s or "")
+ .replace("&", "&")
+ .replace("<", "<")
+ .replace(">", ">")
+ )
+
+
+def _build_html_fragment(sections: Dict[str, str]) -> str:
+ parts = [
+ '',
+ f'
투자위험 / Risk {_xml_escape(sections.get("item1a", ""))} ',
+ f'
소송 {_xml_escape(sections.get("item3", ""))} ',
+ f'
사업의 내용 / MD&A {_xml_escape(sections.get("item7", ""))} ',
+ f'
재무 {_xml_escape(sections.get("item8", ""))} ',
+ f'
내부통제 {_xml_escape(sections.get("item9a", ""))} ',
+ "
'
+ f'
{_esc(sections.get("item1a", ""))} '
+ f'
{_esc(sections.get("item3", ""))} '
+ f'
{_esc(sections.get("item7", ""))} '
+ f'
{_esc(sections.get("item8", ""))} '
+ f'
{_esc(sections.get("item9a", ""))} '
+ "
- `` elements into dicts."""
- items: List[Dict[str, Any]] = []
- if not xml_text:
- return items
+def _feedparser_entries(url: str, default_source: str) -> List[Dict[str, str]]:
+ import feedparser # noqa: WPS433
+
+ items: List[Dict[str, str]] = []
try:
- root = ET.fromstring(xml_text)
- except ET.ParseError:
+ feed = feedparser.parse(url)
+ except Exception:
return items
- for item in root.iter("item"):
- title = (item.findtext("title") or "").strip()
- link = (item.findtext("link") or "").strip()
- pub_date_str = (item.findtext("pubDate") or "").strip()
- description = (item.findtext("description") or "").strip()
- source = (item.findtext("source") or "").strip()
-
- pub_dt: Optional[datetime] = None
- if pub_date_str:
- try:
- pub_dt = parsedate_to_datetime(pub_date_str)
- except (ValueError, TypeError):
- pass
-
+ for e in getattr(feed, "entries", [])[:25]:
+ title = (e.get("title") or "").strip()
+ link = (e.get("link") or e.get("id") or "").strip()
+ pub = (e.get("published") or e.get("updated") or "").strip()
+ src = default_source
+ so = e.get("source")
+ if so:
+ if isinstance(so, dict):
+ src = (so.get("title") or default_source).strip()
+ else:
+ src = str(so).strip() or default_source
if title and link:
items.append({
"title": title,
- "link": link,
- "published": pub_dt.isoformat() if pub_dt else pub_date_str,
- "published_dt": pub_dt,
- "description": description[:500] if description else "",
- "source": source,
+ "source": src,
+ "url": link,
+ "published_at": pub,
+ "summary": (e.get("summary") or "")[:500],
})
return items
-def _dedup_by_title(articles: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
- """Remove duplicate articles based on normalised title."""
- seen: set = set()
- unique: List[Dict[str, Any]] = []
- for art in articles:
- key = re.sub(r"\s+", " ", art["title"].lower().strip())
- if key not in seen:
- seen.add(key)
- unique.append(art)
- return unique
-
-
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-def fetch_finviz_news(ticker: str) -> List[Dict[str, Any]]:
- """Fetch recent news for *ticker* from the Finviz RSS feed.
-
- Parameters
- ----------
- ticker:
- Stock ticker symbol (e.g. ``'AAPL'``).
-
- Returns
- -------
- list[dict]
- Each dict has keys: ``title``, ``link``, ``published``,
- ``description``, ``source``.
- """
+def fetch_google_news_rss(ticker: str) -> List[Dict[str, str]]:
+ """Google News RSS for ``{ticker} stock``."""
if not ticker or not ticker.strip():
return []
- url = f"https://finviz.com/quote.ashx?t={ticker.strip().upper()}&ty=c&p=d&b=1"
- # Finviz RSS endpoint
- rss_url = f"https://finviz.com/news_export.ashx?t={ticker.strip().upper()}"
- xml = _fetch_xml(rss_url)
- if not xml:
+ q = quote_plus(f"{ticker.strip().upper()} stock")
+ url = f"https://news.google.com/rss/search?q={q}&hl=en-US&gl=US&ceid=US:en"
+ return _feedparser_entries(url, "Google News")
+
+
+def fetch_yahoo_finance_rss(ticker: str) -> List[Dict[str, str]]:
+ """Yahoo Finance headline RSS for *ticker*."""
+ if not ticker or not ticker.strip():
return []
- items = _parse_rss_items(xml)
- for item in items:
- if not item.get("source"):
- item["source"] = "Finviz"
- return items
+ sym = ticker.strip().upper()
+ url = (
+ f"https://feeds.finance.yahoo.com/rss/2.0/headline?s={sym}"
+ "®ion=US&lang=en-US"
+ )
+ return _feedparser_entries(url, "Yahoo Finance")
-def fetch_google_news(company_name: str) -> List[Dict[str, Any]]:
- """Fetch recent news for *company_name* from Google News RSS.
-
- Parameters
- ----------
- company_name:
- Full company name (e.g. ``'Apple Inc.'``).
-
- Returns
- -------
- list[dict]
- Same structure as :func:`fetch_finviz_news`.
- """
- if not company_name or not company_name.strip():
- return []
- # URL-encode the query
- query = company_name.strip().replace(" ", "+")
- rss_url = f"https://news.google.com/rss/search?q={query}+stock&hl=en-US&gl=US&ceid=US:en"
- xml = _fetch_xml(rss_url)
- if not xml:
- return []
- items = _parse_rss_items(xml)
- for item in items:
- if not item.get("source"):
- item["source"] = "Google News"
- return items
+def merge_news_for_router(ticker: str, max_articles: int = 40) -> List[Dict[str, str]]:
+ """Finviz (scrape) + Google RSS + Yahoo RSS, title-deduped, Finviz first."""
+ t = ticker.strip().upper()
+ combined: List[Dict[str, str]] = []
+ combined.extend(fetch_finviz_scrape(t))
+ combined.extend(fetch_google_news_rss(t))
+ combined.extend(fetch_yahoo_finance_rss(t))
+ return _dedup_merge(combined, max_articles)
+# Legacy names (backward compatibility if imported elsewhere)
def aggregate_news(
ticker: str,
- company_name: str,
+ company_name: str = "",
max_articles: int = 30,
) -> List[Dict[str, Any]]:
- """Aggregate news from Finviz and Google News, deduplicated and sorted.
-
- Parameters
- ----------
- ticker:
- Stock ticker symbol.
- company_name:
- Full company name for broader search coverage.
- max_articles:
- Maximum number of articles to return (default 30).
-
- Returns
- -------
- list[dict]
- Deduplicated articles sorted by publication time (newest first).
- Each dict has: ``title``, ``link``, ``published``, ``description``,
- ``source``.
- """
- finviz_articles = fetch_finviz_news(ticker)
- google_articles = fetch_google_news(company_name)
-
- all_articles = finviz_articles + google_articles
- unique = _dedup_by_title(all_articles)
-
- # Sort by datetime (newest first); articles without a parseable date go last
- def sort_key(art: Dict[str, Any]) -> float:
- dt = art.get("published_dt")
- if dt is not None:
- return -dt.timestamp()
- return float("inf")
-
- unique.sort(key=sort_key)
-
- # Strip internal datetime field before returning
- for art in unique:
- art.pop("published_dt", None)
-
- return unique[:max_articles]
+ """Deprecated path: use :func:`merge_news_for_router`. *company_name* ignored."""
+ _ = company_name
+ return merge_news_for_router(ticker, max_articles=max_articles)
diff --git a/atlas-terminal/server/services/oecd_cycle.py b/atlas-terminal/server/services/oecd_cycle.py
new file mode 100644
index 0000000..03ce928
--- /dev/null
+++ b/atlas-terminal/server/services/oecd_cycle.py
@@ -0,0 +1,128 @@
+"""OECD leading indicator service via DBnomics."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from server.services.cache import cached
+
+OECD_COUNTRIES = {
+ "USA": "United States",
+ "EA": "Euro Area",
+ "GBR": "United Kingdom",
+ "DEU": "Germany",
+ "FRA": "France",
+ "JPN": "Japan",
+ "KOR": "South Korea",
+ "CHN": "China",
+ "IND": "India",
+ "BRA": "Brazil",
+}
+
+_DATASET = "DSD_STES@DF_CLI"
+
+
+def _fetch_cli(iso: str, limit: int = 36) -> List[Dict[str, Any]]:
+ """Fetch CLI (normalized) for a country from DBnomics."""
+ code = f"{iso}.M.LI.IX._Z.NOR.IX._Z.H"
+ return _fetch_dbn(_DATASET, code, limit)
+
+
+def _fetch_bci(iso: str) -> Optional[float]:
+ code = f"{iso}.M.BCICP.IX._Z.AA.IX._Z.H"
+ series = _fetch_dbn(_DATASET, code, 3)
+ return series[-1]["value"] if series else None
+
+
+def _fetch_cci(iso: str) -> Optional[float]:
+ code = f"{iso}.M.CCICP.IX._Z.AA.IX._Z.H"
+ series = _fetch_dbn(_DATASET, code, 3)
+ return series[-1]["value"] if series else None
+
+
+def _fetch_dbn(dataset: str, series_code: str, limit: int) -> List[Dict[str, Any]]:
+ """Fetch from DBnomics, with REST fallback."""
+ try:
+ import dbnomics
+ df = dbnomics.fetch_series(
+ provider_code="OECD", dataset_code=dataset, series_code=series_code,
+ )
+ if df is None or df.empty:
+ return []
+ df = df.dropna(subset=["value"]).tail(limit)
+ return [
+ {"date": str(row["period"])[:7], "value": round(float(row["value"]), 4)}
+ for _, row in df.iterrows()
+ ]
+ except Exception:
+ return _fetch_dbn_rest(dataset, series_code, limit)
+
+
+def _fetch_dbn_rest(dataset: str, series_code: str, limit: int) -> List[Dict[str, Any]]:
+ """REST fallback when the dbnomics package fails."""
+ import requests
+ url = f"https://api.db.nomics.world/v22/series/OECD/{dataset}/{series_code}?observations=1&limit=1"
+ try:
+ resp = requests.get(url, timeout=15)
+ data = resp.json()
+ docs = data.get("series", {}).get("docs", [])
+ if not docs:
+ return []
+ obs = docs[0]
+ periods = obs.get("period", [])
+ values = obs.get("value", [])
+ result = []
+ for p, v in zip(periods[-limit:], values[-limit:]):
+ if v is not None and str(v) != "NA":
+ try:
+ result.append({"date": str(p)[:7], "value": round(float(v), 4)})
+ except (TypeError, ValueError):
+ continue
+ return result
+ except Exception:
+ return []
+
+
+def _direction(series: List[Dict[str, Any]]) -> str:
+ if len(series) < 2:
+ return "unknown"
+ last = series[-1]["value"]
+ prev = series[-2]["value"]
+ if last > 100 and last > prev:
+ return "expanding"
+ if last < 100 and last < prev:
+ return "contracting"
+ if last > prev:
+ return "recovering"
+ return "slowing"
+
+
+@cached("oecd_cli_snapshot", ttl_seconds=21600)
+def get_oecd_cli_snapshot() -> Dict[str, Any]:
+ """Fetch OECD CLI for major economies via DBnomics."""
+ countries: List[Dict[str, Any]] = []
+
+ for iso, name in OECD_COUNTRIES.items():
+ series = _fetch_cli(iso, limit=36)
+ cli_current = series[-1]["value"] if series else None
+ cli_prev = series[-2]["value"] if len(series) >= 2 else None
+
+ bci = _fetch_bci(iso)
+ cci = _fetch_cci(iso)
+
+ countries.append({
+ "country": name,
+ "iso": iso,
+ "cli_current": cli_current,
+ "cli_prev": cli_prev,
+ "direction": _direction(series) if series else "unknown",
+ "bci": bci,
+ "cci": cci,
+ "series": series,
+ })
+
+ return {
+ "updated_at": datetime.utcnow().isoformat() + "Z",
+ "countries": countries,
+ }
diff --git a/atlas-terminal/server/services/peer_comparison_service.py b/atlas-terminal/server/services/peer_comparison_service.py
new file mode 100644
index 0000000..189a98c
--- /dev/null
+++ b/atlas-terminal/server/services/peer_comparison_service.py
@@ -0,0 +1,115 @@
+"""Peer valuation multiples for overview (yfinance, no LLM)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import yfinance as yf
+
+from server.utils.ticker_utils import SECTORS
+from server.utils.safe_float import _safe_float
+
+# Extra keyword → bucket name (must match keys in SECTORS)
+_BUCKET_KEYWORDS: List[Tuple[str, List[str]]] = [
+ ("Semiconductors & Hardware", ["semiconductor", "semiconductors", "semi ", "hardware"]),
+ ("Software & Cloud", ["software", "cloud", "saas", "internet content"]),
+ ("Consumer Retail", ["retail", "consumer", "restaurant", "specialty retail"]),
+ ("Financial Services", ["financial", "bank", "insurance", "capital market"]),
+ ("Healthcare", ["health", "drug", "biotech", "medical"]),
+]
+
+
+def _match_bucket(sector: str, industry: str) -> Optional[str]:
+ text = f"{sector} {industry}".lower()
+ for bucket, kws in _BUCKET_KEYWORDS:
+ if any(kw in text for kw in kws):
+ return bucket
+ for bucket_name in SECTORS:
+ parts = bucket_name.lower().replace("&", " ").split()
+ if any(p in text for p in parts if len(p) > 3):
+ return bucket_name
+ return None
+
+
+def _fallback_large_caps(sector: str) -> List[str]:
+ s = (sector or "").lower()
+ if "technology" in s or "tech" in s:
+ return ["MSFT", "AAPL", "GOOGL", "META", "NVDA"]
+ if "financial" in s or "financials" in s:
+ return ["JPM", "BAC", "GS", "MS", "V"]
+ if "health" in s:
+ return ["UNH", "JNJ", "LLY", "ABBV", "MRK"]
+ if "consumer" in s:
+ return ["AMZN", "WMT", "HD", "MCD", "SBUX"]
+ return ["MSFT", "AAPL", "GOOGL", "AMZN", "JPM"]
+
+
+def _peer_symbols(ticker: str, sector: str, industry: str) -> List[str]:
+ t = ticker.upper().strip()
+ bucket = _match_bucket(sector, industry)
+ if bucket and bucket in SECTORS:
+ syms = list(SECTORS[bucket])
+ else:
+ syms = _fallback_large_caps(sector)
+ if t not in syms:
+ syms = [t] + [x for x in syms if x != t]
+ # unique preserve order, cap 8
+ seen: set[str] = set()
+ out: List[str] = []
+ for s in syms:
+ u = s.upper()
+ if u not in seen:
+ seen.add(u)
+ out.append(u)
+ if len(out) >= 8:
+ break
+ return out
+
+
+def _peer_row(sym: str) -> Dict[str, Any]:
+ info = (yf.Ticker(sym).info) or {}
+ return {
+ "ticker": sym,
+ "name": str(info.get("shortName") or info.get("longName") or sym)[:80],
+ "market_cap": _safe_float(info.get("marketCap")),
+ "pe": _safe_float(info.get("trailingPE")) or _safe_float(info.get("forwardPE")),
+ "pb": _safe_float(info.get("priceToBook")),
+ "ps": _safe_float(info.get("priceToSalesTrailing12Months")),
+ "ev_ebitda": _safe_float(info.get("enterpriseToEbitda")),
+ }
+
+
+def _avg(vals: List[Optional[float]]) -> Optional[float]:
+ nums = [v for v in vals if v is not None]
+ if not nums:
+ return None
+ return round(sum(nums) / len(nums), 2)
+
+
+def build_peer_comparison(ticker: str) -> Dict[str, Any]:
+ """Return payload matching PeerComparisonData on the frontend."""
+ t = ticker.upper().strip()
+ try:
+ info = (yf.Ticker(t).info) or {}
+ except Exception:
+ info = {}
+ sector = str(info.get("sector") or "")
+ industry = str(info.get("industry") or "")
+ syms = _peer_symbols(t, sector, industry)
+ peers = [_peer_row(s) for s in syms]
+ pes = [p["pe"] for p in peers]
+ pbs = [p["pb"] for p in peers]
+ pss = [p["ps"] for p in peers]
+ evs = [p["ev_ebitda"] for p in peers]
+ return {
+ "ticker": t,
+ "sector": sector or "—",
+ "industry": industry or "—",
+ "averages": {
+ "pe": _avg(pes),
+ "pb": _avg(pbs),
+ "ps": _avg(pss),
+ "ev_ebitda": _avg(evs),
+ },
+ "peers": peers,
+ }
diff --git a/atlas-terminal/server/services/research_dashboard.py b/atlas-terminal/server/services/research_dashboard.py
new file mode 100644
index 0000000..8d5ed93
--- /dev/null
+++ b/atlas-terminal/server/services/research_dashboard.py
@@ -0,0 +1,381 @@
+"""Research deep-dive dashboard: F-Score history, DuPont tree, Sankey, waterfall, anomalies.
+
+All quantitative; no LLM. See claude.md hybrid separation principle.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+
+from server.utils.safe_float import _safe_float
+from server.services.market_fetcher import _get_annual_financials_balance_cashflow, _get_row_series
+from server.services.financial_metrics import get_dupont_altman_redflags_yoy
+from server.services.financial_metrics_ext import get_income_statement_sankey_data
+from server.models.schemas import (
+ DuPontTreeNode,
+ DuPontTreePayload,
+ FScoreCriterionSeries,
+ FScoreYearPoint,
+ FinancialAnomalyItem,
+ ResearchDashboardResponse,
+ SankeyGraphPayload,
+ SankeyNivoLink,
+ SankeyNivoNode,
+ WaterfallStep,
+)
+
+try:
+ import yfinance as yf
+except ImportError:
+ yf = None # type: ignore[assignment]
+
+_FSCORE_KEYS = [
+ ("profitable", "Net income > 0"),
+ ("ocf_pos", "Operating cash flow > 0"),
+ ("roa_up", "ROA vs prior year"),
+ ("ocf_gt_ni", "OCF > net income"),
+ ("leverage_down", "Lower LT debt / assets"),
+ ("cr_up", "Current ratio improved"),
+ ("no_dilution", "Shares flat or down"),
+ ("gm_up", "Gross margin improved"),
+ ("at_up", "Asset turnover improved"),
+]
+
+
+def _col_year(fin: pd.DataFrame, idx: int) -> int:
+ if fin is None or fin.empty or idx >= len(fin.columns):
+ return 0
+ c = fin.columns[idx]
+ s = str(c)[:4]
+ return int(s) if s.isdigit() else 2024 - idx
+
+
+def _vx(s: Optional[pd.Series], i: int) -> Optional[float]:
+ if s is None or len(s) <= i:
+ return None
+ x = _safe_float(s.iloc[i])
+ return x if x is not None and x == x and not pd.isna(x) else None
+
+
+def _fscore_passes_for_pair(
+ fin: pd.DataFrame,
+ bal: pd.DataFrame,
+ cf: pd.DataFrame,
+ ticker: str,
+ i: int,
+) -> Tuple[bool, ...]:
+ """Piotroski 9 booleans comparing fiscal column i vs i+1 (i is more recent)."""
+ ncol = len(fin.columns)
+ if i + 1 >= ncol:
+ return tuple([False] * 9)
+
+ rev = _get_row_series(fin, "Total Revenue", "Revenue")
+ ni = _get_row_series(fin, "Net Income", "Net Income Common Stockholders")
+ gross = _get_row_series(fin, "Gross Profit")
+ ta = _get_row_series(bal, "Total Assets")
+ lt_debt = _get_row_series(bal, "Long Term Debt")
+ ca = _get_row_series(bal, "Current Assets")
+ cl = _get_row_series(bal, "Current Liabilities")
+ ocf = _get_row_series(cf, "Operating Cash Flow", "Cash From Operating Activities") if not cf.empty else None
+ shares = _get_row_series(bal, "Share Issued")
+ if shares is None or (hasattr(shares, "empty") and shares.empty):
+ shares = _get_row_series(bal, "Ordinary Shares Number")
+
+ ni0, ni1 = _vx(ni, i), _vx(ni, i + 1)
+ ocf0 = _vx(ocf, i) if ocf is not None else None
+ ta0, ta1 = _vx(ta, i), _vx(ta, i + 1)
+ roa0 = (ni0 / ta0 * 100) if (ni0 is not None and ta0 and ta0 != 0) else None
+ roa1 = (ni1 / ta1 * 100) if (ni1 is not None and ta1 and ta1 != 0) else None
+ lt0 = _vx(lt_debt, i) or 0
+ lt1 = _vx(lt_debt, i + 1) or 0
+ cl0, cl1 = _vx(cl, i), _vx(cl, i + 1)
+ ca0, ca1 = _vx(ca, i), _vx(ca, i + 1)
+ cr0 = (ca0 / cl0) if (ca0 is not None and cl0 and cl0 != 0) else None
+ cr1 = (ca1 / cl1) if (ca1 is not None and cl1 and cl1 != 0) else None
+ sh0, sh1 = _vx(shares, i), _vx(shares, i + 1)
+ rev0, rev1 = _vx(rev, i), _vx(rev, i + 1)
+ gm0 = (_vx(gross, i) / rev0 * 100) if (gross is not None and rev0 and rev0 != 0) else None
+ gm1 = (_vx(gross, i + 1) / rev1 * 100) if (gross is not None and rev1 and rev1 != 0) else None
+ at0 = (rev0 / ta0) if (rev0 and ta0 and ta0 != 0) else None
+ at1 = (rev1 / ta1) if (rev1 and ta1 and ta1 != 0) else None
+
+ if shares is None or (sh0 is None and sh1 is None) and yf:
+ try:
+ info = (yf.Ticker(ticker.upper()).info) or {}
+ sh_out = info.get("sharesOutstanding")
+ if sh_out is not None:
+ sh0 = sh0 or _safe_float(sh_out)
+ except Exception:
+ pass
+
+ p1 = ni0 is not None and ni0 > 0
+ p2 = ocf0 is not None and ocf0 > 0
+ p3 = roa0 is not None and roa1 is not None and roa0 > roa1
+ p4 = ocf0 is not None and ni0 is not None and ocf0 > ni0
+ p5 = bool(ta0 and ta0 != 0 and ta1 and ta1 != 0 and (lt0 / ta0) < (lt1 / ta1))
+ p6 = cr0 is not None and cr1 is not None and cr0 > cr1
+ p7 = (sh0 is not None and sh1 is not None and sh0 <= sh1) if (sh0 is not None and sh1 is not None) else True
+ p8 = gm0 is not None and gm1 is not None and gm0 > gm1
+ p9 = at0 is not None and at1 is not None and at0 > at1
+ return (p1, p2, p3, p4, p5, p6, p7, p8, p9)
+
+
+def _build_fscore_series(ticker: str, fin: pd.DataFrame, bal: pd.DataFrame, cf: pd.DataFrame) -> Tuple[int, List[FScoreCriterionSeries]]:
+ criteria_out: List[FScoreCriterionSeries] = []
+ ncol = len(fin.columns)
+ if ncol < 2:
+ return 0, []
+
+ max_pairs = min(3, ncol - 1)
+ latest_passes = _fscore_passes_for_pair(fin, bal, cf, ticker, 0)
+ total = sum(1 for p in latest_passes if p)
+
+ for ci, (key, label) in enumerate(_FSCORE_KEYS):
+ hist: List[FScoreYearPoint] = []
+ for k in range(max_pairs):
+ passes = _fscore_passes_for_pair(fin, bal, cf, ticker, k)
+ yr = _col_year(fin, k)
+ hist.append(FScoreYearPoint(year=yr, pass_flag=bool(passes[ci])))
+ criteria_out.append(FScoreCriterionSeries(key=key, label=label, history=list(reversed(hist))))
+
+ return total, criteria_out
+
+
+def _dupont_tree_from_df(dupont_df: pd.DataFrame) -> Optional[DuPontTreePayload]:
+ if dupont_df is None or dupont_df.empty:
+ return None
+ row0 = dupont_df.iloc[0]
+ npm = float(row0.get("NPM %") or 0)
+ at = float(row0.get("Asset Turnover") or 0)
+ em = float(row0.get("Equity Mult.") or 0)
+ roe = float(row0.get("ROE %") or 0)
+
+ tail = dupont_df.iloc[1:6]
+ def avg(col: str) -> Optional[float]:
+ if col not in tail.columns:
+ return None
+ s = tail[col].dropna()
+ if s.empty:
+ return None
+ return float(s.mean())
+
+ def node(
+ nid: str,
+ lbl: str,
+ val: float,
+ unit: str,
+ col: str,
+ ) -> DuPontTreeNode:
+ a = avg(col)
+ vs = ((val - a) / abs(a) * 100) if (a is not None and a != 0) else None
+ if vs is None:
+ tr = "flat"
+ elif vs > 2:
+ tr = "up"
+ elif vs < -2:
+ tr = "down"
+ else:
+ tr = "flat"
+ return DuPontTreeNode(
+ id=nid,
+ label=lbl,
+ value=round(val, 4),
+ unit=unit,
+ avg_5y=round(a, 4) if a is not None else None,
+ vs_5y_avg_pct=round(vs, 2) if vs is not None else None,
+ trend=tr,
+ )
+
+ root = node("roe", "ROE", roe, "pct", "ROE %")
+ return DuPontTreePayload(
+ root=root,
+ npm=node("npm", "Net margin", npm, "pct", "NPM %"),
+ asset_turnover=node("at", "Asset turnover", at, "x", "Asset Turnover"),
+ equity_mult=node("em", "Equity multiplier", em, "x", "Equity Mult."),
+ )
+
+
+def _build_sankey_nivo(ticker: str) -> SankeyGraphPayload:
+ d = get_income_statement_sankey_data(ticker)
+ rev = max(d.get("revenue") or 0, 1)
+ cogs = min(abs(d.get("cogs") or 0), rev * 0.999)
+ gp = max(d.get("gross_profit") or 0, 0)
+ opex = max(d.get("opex") or 0, 0)
+ oi = d.get("operating_income") or 0
+ tax = max(d.get("tax_interest_other") or 0, 0)
+ ni = d.get("net_income") or 0
+
+ nodes = [
+ SankeyNivoNode(id="revenue", label="Revenue"),
+ SankeyNivoNode(id="cogs", label="COGS"),
+ SankeyNivoNode(id="gross_profit", label="Gross profit"),
+ SankeyNivoNode(id="opex", label="Operating expenses"),
+ SankeyNivoNode(id="operating_income", label="Operating income"),
+ SankeyNivoNode(id="tax_other", label="Tax & other"),
+ SankeyNivoNode(id="net_income", label="Net income"),
+ ]
+ links: List[SankeyNivoLink] = [
+ SankeyNivoLink(source="revenue", target="cogs", value=float(cogs)),
+ SankeyNivoLink(source="revenue", target="gross_profit", value=float(max(gp, rev - cogs))),
+ ]
+ gp_v = links[-1].value
+ links.append(SankeyNivoLink(source="gross_profit", target="opex", value=float(min(opex, gp_v))))
+ links.append(SankeyNivoLink(source="gross_profit", target="operating_income", value=float(max(oi, gp_v - opex))))
+ oi_v = links[-1].value
+ tax_v = min(tax, max(oi_v, 0))
+ links.append(SankeyNivoLink(source="operating_income", target="tax_other", value=float(tax_v)))
+ links.append(SankeyNivoLink(source="operating_income", target="net_income", value=float(max(abs(ni), 0))))
+ return SankeyGraphPayload(nodes=nodes, links=links)
+
+
+def _build_waterfall(fin: pd.DataFrame) -> List[WaterfallStep]:
+ if fin is None or fin.empty or len(fin.columns) < 2:
+ return []
+ c0, c1 = fin.columns[0], fin.columns[1]
+
+ def cell(row_names: Tuple[str, ...]) -> Tuple[float, float]:
+ v0 = v1 = 0.0
+ for name in row_names:
+ if name in fin.index:
+ v0 += float(_safe_float(fin.loc[name, c0]) or 0)
+ v1 += float(_safe_float(fin.loc[name, c1]) or 0)
+ return v0, v1
+
+ gp0, gp1 = cell(("Gross Profit",))
+ if gp0 == 0 and gp1 == 0:
+ r0, r1 = cell(("Total Revenue", "Revenue"))
+ cg0, cg1 = cell(("Cost Of Revenue", "Cost of Revenue"))
+ gp0, gp1 = r0 - cg0, r1 - cg1
+
+ oi0, oi1 = cell(("Operating Income", "EBIT"))
+ opex0 = max(gp0 - oi0, 0)
+ opex1 = max(gp1 - oi1, 0)
+
+ d_gp = gp0 - gp1
+ d_opex = opex0 - opex1
+
+ y0 = _col_year(fin, 0)
+ y1 = _col_year(fin, 1)
+ cum = oi1
+ steps: List[WaterfallStep] = [
+ WaterfallStep(id="prior_oi", label=f"Operating income {y1}", value=oi1, cumulative=cum, step_type="total"),
+ WaterfallStep(id="d_gp", label="Gross profit change", value=d_gp, cumulative=cum + d_gp, step_type="relative"),
+ WaterfallStep(id="d_opex", label="Operating expense change", value=-d_opex, cumulative=cum + d_gp - d_opex, step_type="relative"),
+ ]
+ final = cum + d_gp - d_opex
+ diff = oi0 - final
+ if abs(diff) > max(abs(oi0), 1) * 0.02:
+ steps.append(WaterfallStep(id="other", label="Other / rounding", value=diff, cumulative=oi0, step_type="relative"))
+ steps.append(WaterfallStep(id="current_oi", label=f"Operating income {y0}", value=oi0, cumulative=oi0, step_type="total"))
+ return steps
+
+
+_ANOMALY_ROWS = [
+ ("Total Revenue", "Revenue"),
+ ("Cost Of Revenue", "COGS"),
+ ("Research And Development", "R&D"),
+ ("Selling General And Administration", "SG&A"),
+ ("Operating Expense", "Operating expenses"),
+ ("Operating Income", "Operating income"),
+ ("Net Income", "Net income"),
+ ("Total Debt", "Total debt"),
+ ("Long Term Debt", "Long-term debt"),
+ ("Current Debt", "Short-term debt"),
+]
+
+
+def _detect_anomalies(fin: pd.DataFrame, bal: pd.DataFrame, threshold: float = 0.30) -> List[FinancialAnomalyItem]:
+ out: List[FinancialAnomalyItem] = []
+ if fin is None or fin.empty or len(fin.columns) < 2:
+ return out
+ c0, c1 = fin.columns[0], fin.columns[1]
+
+ def check_row(idx_name: str, display: str) -> None:
+ if idx_name not in fin.index:
+ return
+ cur = _safe_float(fin.loc[idx_name, c0])
+ prev = _safe_float(fin.loc[idx_name, c1])
+ if cur is None or prev is None or abs(prev) < 1e-6:
+ return
+ chg = (cur - prev) / abs(prev)
+ if abs(chg) < threshold:
+ return
+ out.append(
+ FinancialAnomalyItem(
+ account_key=idx_name,
+ display_name=display,
+ prior_value=prev,
+ current_value=cur,
+ change_pct=round(chg * 100, 2),
+ direction="up" if chg > 0 else "down",
+ )
+ )
+
+ for key, disp in _ANOMALY_ROWS:
+ check_row(key, disp)
+
+ if bal is not None and not bal.empty and len(bal.columns) >= 2:
+ b0, b1 = bal.columns[0], bal.columns[1]
+ for idx_name, display in [
+ ("Current Debt", "Short-term borrowings"),
+ ("Long Term Debt", "Long-term debt"),
+ ("Total Debt", "Total debt"),
+ ]:
+ if idx_name not in bal.index:
+ continue
+ cur = _safe_float(bal.loc[idx_name, b0])
+ prev = _safe_float(bal.loc[idx_name, b1])
+ if cur is None or prev is None or abs(prev) < 1e-6:
+ continue
+ chg = (cur - prev) / abs(prev)
+ if abs(chg) < threshold:
+ continue
+ out.append(
+ FinancialAnomalyItem(
+ account_key=f"BS:{idx_name}",
+ display_name=display,
+ prior_value=prev,
+ current_value=cur,
+ change_pct=round(chg * 100, 2),
+ direction="up" if chg > 0 else "down",
+ )
+ )
+
+ out.sort(key=lambda x: abs(x.change_pct or 0), reverse=True)
+ return out[:12]
+
+
+def sankey_nivo_for_ticker(ticker: str) -> Dict[str, Any]:
+ """Public helper for /api/market/sankey extended payload."""
+ return _build_sankey_nivo(ticker).model_dump()
+
+
+def build_research_dashboard(ticker: str) -> ResearchDashboardResponse:
+ sym = ticker.upper().strip()
+ fin, bal, cf = _get_annual_financials_balance_cashflow(sym)
+ if fin is None or fin.empty or bal is None or bal.empty:
+ return ResearchDashboardResponse(ticker=sym, error="Insufficient financial statements")
+
+ if cf is None or cf.empty:
+ cf = pd.DataFrame()
+
+ total, fseries = _build_fscore_series(sym, fin, bal, cf)
+ dq = get_dupont_altman_redflags_yoy(sym)
+ dupont_df = dq.get("dupont") if dq else None
+ tree = _dupont_tree_from_df(dupont_df) if isinstance(dupont_df, pd.DataFrame) else None
+
+ sankey = _build_sankey_nivo(sym)
+ waterfall = _build_waterfall(fin)
+ anomalies = _detect_anomalies(fin, bal)
+
+ return ResearchDashboardResponse(
+ ticker=sym,
+ fscore_total=total,
+ fscore_criteria=fseries,
+ dupont_tree=tree,
+ sankey=sankey,
+ waterfall=waterfall,
+ anomalies=anomalies,
+ )
diff --git a/atlas-terminal/server/services/sec_parser.py b/atlas-terminal/server/services/sec_parser.py
index b807f70..6e5570a 100644
--- a/atlas-terminal/server/services/sec_parser.py
+++ b/atlas-terminal/server/services/sec_parser.py
@@ -13,6 +13,7 @@ from pathlib import Path
from typing import Dict, List, Optional
from bs4 import BeautifulSoup
+from bs4.element import Comment, Tag
from server.services.text_chunker import clean_text_for_llm, smart_chunk
@@ -257,6 +258,194 @@ def get_main_10k_text(filing_dir: Path) -> str:
return main_text
+def get_main_10k_html_path(filing_dir: Path) -> Optional[Path]:
+ """Pick the largest ``.htm`` / ``.html`` file (primary 10-K document)."""
+ best: Optional[Path] = None
+ best_size = 0
+ for path in filing_dir.rglob("*.htm*"):
+ try:
+ sz = path.stat().st_size
+ if sz > best_size:
+ best_size = sz
+ best = path
+ except OSError:
+ continue
+ return best
+
+
+def read_main_10k_html_raw(filing_dir: Path) -> str:
+ """Read raw HTML from the main filing document."""
+ path = get_main_10k_html_path(filing_dir)
+ if not path:
+ return ""
+ for enc in ("utf-8", "latin-1"):
+ try:
+ return path.read_text(encoding=enc, errors="replace")
+ except Exception:
+ continue
+ return ""
+
+
+def _strip_scripts_keep_html(html: str) -> str:
+ """Remove ``