aria-code 4.1.3__py3-none-any.whl

datasources/sources/alpha_vantage_source.py

@@ -0,0 +1,202 @@
+"""
+datasources/sources/alpha_vantage_source.py — Alpha Vantage 免费层数据
+======================================================================
+免费 API key 从 https://www.alphavantage.co/support/#api-key 申请（秒得）。
+免费限制: 25 请求/天，5 请求/分钟。
+
+功能: 美股/ETF 行情、技术指标、外汇汇率、大宗商品、基本面数据。
+
+配置: ALPHA_VANTAGE_KEY 环境变量 或 ~/.aria/.env
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+import urllib.request
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Dict, Optional
+
+from ..base import BaseDataSource, FundamentalsResult, HistoryResult, QuoteResult
+
+logger = logging.getLogger(__name__)
+
+_BASE = "https://www.alphavantage.co/query"
+
+
+def _load_key() -> str:
+    key = os.getenv("ALPHA_VANTAGE_KEY", "") or os.getenv("ALPHAVANTAGE_KEY", "")
+    if not key:
+        for p in [Path.home() / ".aria" / ".env", Path.home() / ".arthera" / ".env"]:
+            if p.exists():
+                for line in p.read_text(encoding="utf-8").splitlines():
+                    if line.startswith(("ALPHA_VANTAGE_KEY=", "ALPHAVANTAGE_KEY=")):
+                        key = line.split("=", 1)[1].strip()
+                        break
+            if key:
+                break
+    if not key:
+        # providers.json 中存储的键名是 "alphavantage"（无下划线）
+        try:
+            import json as _json
+            _p = Path.home() / ".arthera" / "providers.json"
+            if _p.exists():
+                _raw = _json.loads(_p.read_text(encoding="utf-8"))
+                key = (
+                    _raw.get("data", {}).get("alphavantage", {}).get("api_key", "")
+                    or _raw.get("data", {}).get("alpha_vantage", {}).get("api_key", "")
+                )
+        except Exception:
+            pass
+    return key
+
+
+def _fetch(params: dict, timeout: int = 15) -> Optional[dict]:
+    import json
+    qs = "&".join(f"{k}={v}" for k, v in params.items())
+    url = f"{_BASE}?{qs}"
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "aria-code/1.0"})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except Exception as e:
+        logger.debug(f"[alpha_vantage] fetch 失败: {e}")
+        return None
+
+
+class AlphaVantageSource(BaseDataSource):
+    """
+    Alpha Vantage 数据源。
+    免费 key 足够日常使用（25次/天）；付费 key 无频率限制。
+    """
+
+    name         = "alpha_vantage"
+    markets      = ["us", "hk", "forex", "commodity"]
+    requires_key = True
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        self._key = _load_key()
+
+    def is_configured(self) -> bool:
+        return bool(self._key)
+
+    def quote(self, symbol: str) -> Optional[QuoteResult]:
+        data = _fetch({"function": "GLOBAL_QUOTE", "symbol": symbol, "apikey": self._key})
+        if not data:
+            return None
+        q = data.get("Global Quote", {})
+        if not q or "05. price" not in q:
+            return None
+        price  = float(q.get("05. price", 0))
+        change = float(q.get("09. change", 0))
+        pct    = float(q.get("10. change percent", "0%").replace("%", ""))
+        vol    = float(q.get("06. volume", 0))
+        return QuoteResult(
+            symbol     = symbol,
+            price      = price,
+            change     = change,
+            change_pct = pct,
+            volume     = vol,
+            market     = "us",
+            source     = self.name,
+            timestamp  = q.get("07. latest trading day", ""),
+        )
+
+    def history(
+        self,
+        symbol: str,
+        days: int = 365,
+        interval: str = "1d",
+    ) -> Optional[HistoryResult]:
+        try:
+            import pandas as pd
+            size   = "compact" if days <= 100 else "full"
+            func   = "TIME_SERIES_DAILY_ADJUSTED"
+            data   = _fetch({"function": func, "symbol": symbol,
+                             "outputsize": size, "apikey": self._key})
+            if not data:
+                return None
+            ts = data.get("Time Series (Daily)", {})
+            if not ts:
+                return None
+            cutoff = (date.today() - timedelta(days=days)).isoformat()
+            rows   = []
+            for d, v in ts.items():
+                if d < cutoff:
+                    continue
+                rows.append({
+                    "date":   d,
+                    "open":   float(v.get("1. open", 0)),
+                    "high":   float(v.get("2. high", 0)),
+                    "low":    float(v.get("3. low", 0)),
+                    "close":  float(v.get("5. adjusted close", v.get("4. close", 0))),
+                    "volume": float(v.get("6. volume", 0)),
+                })
+            if not rows:
+                return None
+            df = pd.DataFrame(rows)
+            df["date"] = pd.to_datetime(df["date"])
+            df = df.set_index("date").sort_index()
+            return HistoryResult(symbol=symbol, data=df, source=self.name, interval="1d")
+        except Exception as e:
+            logger.debug(f"[alpha_vantage] history {symbol} 失败: {e}")
+            return None
+
+    def fundamentals(self, symbol: str) -> Optional[FundamentalsResult]:
+        data = _fetch({"function": "OVERVIEW", "symbol": symbol, "apikey": self._key})
+        if not data or not data.get("Symbol"):
+            return None
+        def _f(k, mult: float = 1.0):
+            v = data.get(k, "None")
+            try:
+                fv = float(v) if v not in ("None", "-", "", "0") else None
+                return fv * mult if fv is not None else None
+            except ValueError:
+                return None
+        return FundamentalsResult(
+            symbol          = symbol,
+            pe_ttm          = _f("TrailingPE"),
+            pb              = _f("PriceToBookRatio"),
+            roe             = _f("ReturnOnEquityTTM", 100),
+            revenue_growth  = _f("RevenueGrowthQtrlyYOY"),
+            dividend_yield  = _f("DividendYield", 100),
+            source          = self.name,
+        )
+
+    def get_forex(self, from_currency: str, to_currency: str) -> Optional[Dict]:
+        """实时外汇汇率。"""
+        data = _fetch({"function": "CURRENCY_EXCHANGE_RATE",
+                       "from_currency": from_currency,
+                       "to_currency": to_currency,
+                       "apikey": self._key})
+        if not data:
+            return None
+        r = data.get("Realtime Currency Exchange Rate", {})
+        return {
+            "from": from_currency, "to": to_currency,
+            "rate": float(r.get("5. Exchange Rate", 0)),
+            "time": r.get("6. Last Refreshed", ""),
+        }
+
+    def get_commodity(self, symbol: str = "WTI") -> Optional[HistoryResult]:
+        """大宗商品历史价格（WTI/BRENT/GOLD/COPPER 等）。"""
+        _MAP = {"WTI": "WTI", "BRENT": "BRENT", "GOLD": "GOLD",
+                "COPPER": "COPPER", "ALUMINUM": "ALUMINUM", "WHEAT": "WHEAT"}
+        func = _MAP.get(symbol.upper(), symbol.upper())
+        data = _fetch({"function": func, "interval": "monthly", "apikey": self._key})
+        if not data:
+            return None
+        try:
+            import pandas as pd
+            rows = [{"date": r["date"], "close": float(r["value"])}
+                    for r in data.get("data", []) if r.get("value") not in (".", None)]
+            df = pd.DataFrame(rows)
+            df["date"] = pd.to_datetime(df["date"])
+            df = df.set_index("date").sort_index()
+            return HistoryResult(symbol=symbol, data=df, source=self.name, interval="1mo")
+        except Exception as e:
+            logger.debug(f"[alpha_vantage] commodity {symbol} 失败: {e}")
+            return None

datasources/sources/edgar_source.py

@@ -0,0 +1,218 @@
+"""
+datasources/sources/edgar_source.py — SEC EDGAR 美国上市公司财务数据
+====================================================================
+完全免费，无需 API key。数据来源：https://data.sec.gov (SEC EDGAR API)
+覆盖：10-K / 10-Q 财报、公司基本信息、财务报表、内幕交易披露。
+
+用法:
+    src = EDGARSource()
+    facts = src.get_company_facts("AAPL")   # → 财务指标历史
+    filings = src.get_recent_filings("MSFT") # → 最近10-K/10-Q
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+from ..base import BaseDataSource, FundamentalsResult, QuoteResult
+
+import os as _os
+
+logger = logging.getLogger(__name__)
+
+_EDGAR_API    = "https://data.sec.gov"
+_EDGAR_WWW    = "https://www.sec.gov"
+_HEADERS      = {
+    "User-Agent": _os.environ.get("EDGAR_USER_AGENT", "aria-code contact@example.com"),  # SEC requires self-identification
+    "Accept-Encoding": "gzip, deflate",
+}
+
+# 主要美股 ticker → CIK 缓存（常用的直接查，避免每次API调用）
+_TICKER_CIK_CACHE: Dict[str, str] = {}
+
+
+def _fetch_json(url: str, timeout: int = 15) -> Optional[Dict]:
+    try:
+        import gzip, json
+        req = urllib.request.Request(url, headers=_HEADERS)
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+            if resp.headers.get("Content-Encoding") == "gzip":
+                raw = gzip.decompress(raw)
+            return json.loads(raw)
+    except Exception as e:
+        logger.debug(f"[edgar] fetch {url} 失败: {e}")
+        return None
+
+
+class EDGARSource(BaseDataSource):
+    """
+    SEC EDGAR 数据源 — 美国上市公司财报和披露文件。
+    """
+
+    name         = "edgar"
+    markets      = ["us"]
+    requires_key = False
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        self._tickers: Optional[Dict] = None
+        self._cik_map: Dict[str, str] = {}
+
+    def is_configured(self) -> bool:
+        return True
+
+    def _load_ticker_map(self) -> None:
+        """加载 SEC 全量 ticker→CIK 映射（首次调用时下载一次）"""
+        if self._tickers is not None:
+            return
+        data = _fetch_json(f"{_EDGAR_WWW}/files/company_tickers.json")
+        if data:
+            for v in data.values():
+                ticker = v.get("ticker", "").upper()
+                cik    = str(v.get("cik_str", "")).zfill(10)
+                if ticker:
+                    self._cik_map[ticker] = cik
+        self._tickers = self._cik_map
+
+    def ticker_to_cik(self, symbol: str) -> Optional[str]:
+        self._load_ticker_map()
+        return self._cik_map.get(symbol.upper())
+
+    def get_company_facts(self, symbol: str) -> Optional[Dict[str, Any]]:
+        """
+        获取公司全部财务事实（XBRL 格式）。
+        返回包含 EPS/Revenue/NetIncome/Assets 等历史序列的字典。
+        """
+        cik = self.ticker_to_cik(symbol)
+        if not cik:
+            return {"error": f"未找到 {symbol} 的 CIK"}
+        data = _fetch_json(f"{_EDGAR_API}/api/xbrl/companyfacts/CIK{cik}.json")
+        if not data:
+            return None
+
+        us_gaap = data.get("facts", {}).get("us-gaap", {})
+        result  = {"symbol": symbol, "cik": cik, "metrics": {}}
+        wanted  = {
+            "Revenues": "revenue",
+            "RevenueFromContractWithCustomerExcludingAssessedTax": "revenue",
+            "NetIncomeLoss": "net_income",
+            "EarningsPerShareBasic": "eps_basic",
+            "EarningsPerShareDiluted": "eps_diluted",
+            "Assets": "total_assets",
+            "LiabilitiesAndStockholdersEquity": "total_equity",
+            "OperatingIncomeLoss": "operating_income",
+            "CommonStockSharesOutstanding": "shares_outstanding",
+        }
+        for gaap_key, alias in wanted.items():
+            if gaap_key in us_gaap:
+                units = us_gaap[gaap_key].get("units", {})
+                unit_key = "USD" if "USD" in units else ("shares" if "shares" in units else next(iter(units), None))
+                if unit_key and unit_key in units:
+                    entries = [
+                        {"end": e["end"], "val": e["val"], "form": e.get("form", "")}
+                        for e in units[unit_key]
+                        if e.get("form") in ("10-K", "10-Q", "20-F")
+                    ]
+                    if entries:
+                        entries.sort(key=lambda x: x["end"], reverse=True)
+                        result["metrics"][alias] = entries[:20]
+        return result
+
+    def get_recent_filings(self, symbol: str, form_types: List[str] = None) -> List[Dict]:
+        """获取最近提交的财务报告（10-K、10-Q、8-K 等）。"""
+        cik = self.ticker_to_cik(symbol)
+        if not cik:
+            return [{"error": f"未找到 {symbol} 的 CIK"}]
+        form_types = form_types or ["10-K", "10-Q", "8-K"]
+        data = _fetch_json(f"{_EDGAR_API}/submissions/CIK{cik}.json")
+        if not data:
+            return []
+
+        recent   = data.get("filings", {}).get("recent", {})
+        forms    = recent.get("form", [])
+        dates    = recent.get("filingDate", [])
+        accnos   = recent.get("accessionNumber", [])
+        docs     = recent.get("primaryDocument", [])
+
+        results = []
+        for form, filing_date, accno, doc in zip(forms, dates, accnos, docs):
+            if form in form_types:
+                accno_clean = accno.replace("-", "")
+                url = f"https://www.sec.gov/Archives/edgar/data/{int(cik)}/{accno_clean}/{doc}"
+                results.append({
+                    "form": form,
+                    "date": filing_date,
+                    "accession": accno,
+                    "url": url,
+                    "cik": cik,
+                })
+            if len(results) >= 20:
+                break
+        return results
+
+    def get_insider_trades(self, symbol: str, days: int = 90) -> List[Dict]:
+        """获取内幕交易披露（Form 4）。"""
+        cik = self.ticker_to_cik(symbol)
+        if not cik:
+            return []
+        data = _fetch_json(f"{_EDGAR_API}/submissions/CIK{cik}.json")
+        if not data:
+            return []
+
+        recent = data.get("filings", {}).get("recent", {})
+        forms  = recent.get("form", [])
+        dates  = recent.get("filingDate", [])
+        results = []
+        from datetime import date as _date, timedelta as _td
+        cutoff = (_date.today() - _td(days=days)).isoformat()
+
+        for form, filing_date in zip(forms, dates):
+            if form == "4" and filing_date >= cutoff:
+                results.append({"form": "4", "date": filing_date, "type": "insider"})
+            if len(results) >= 30:
+                break
+        return results
+
+    def quote(self, symbol: str) -> Optional[QuoteResult]:
+        facts = self.get_company_facts(symbol)
+        if not facts or "metrics" in facts and not facts["metrics"]:
+            return None
+        m = facts.get("metrics", {})
+        rev = m.get("revenue", [{}])[0].get("val", 0) if m.get("revenue") else 0
+        return QuoteResult(
+            symbol  = symbol,
+            name    = f"EDGAR:{symbol}",
+            price   = 0.0,
+            market  = "us",
+            source  = self.name,
+            extra   = {"annual_revenue": rev},
+        )
+
+    def fundamentals(self, symbol: str) -> Optional[FundamentalsResult]:
+        facts = self.get_company_facts(symbol)
+        if not facts:
+            return None
+        m = facts.get("metrics", {})
+
+        def _latest(key: str) -> float:
+            entries = m.get(key, [])
+            return float(entries[0]["val"]) if entries else 0.0
+
+        net_income = _latest("net_income")
+        revenue    = _latest("revenue")
+        rev_yoy    = 0.0
+        if m.get("revenue") and len(m["revenue"]) >= 2:
+            cur  = float(m["revenue"][0]["val"])
+            prev = float(m["revenue"][1]["val"])
+            if prev:
+                rev_yoy = (cur - prev) / abs(prev) * 100
+
+        return FundamentalsResult(
+            symbol           = symbol,
+            revenue_growth   = rev_yoy,
+            source           = self.name,
+        )

datasources/sources/finnhub_source.py

@@ -0,0 +1,197 @@
+"""
+datasources/sources/finnhub_source.py — Finnhub 美股/港股数据源
+================================================================
+使用 ~/.arthera/providers.json 中配置的 Finnhub API key，
+提供实时行情、历史 K 线、基本面数据。
+免费套餐：每分钟 60 次请求，支持美股 / ETF / 指数 / 外汇 / 加密。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import time
+import urllib.request
+from datetime import datetime, timedelta, date, timezone
+from pathlib import Path
+from typing import Optional
+
+import pandas as pd
+
+from ..base import BaseDataSource, FundamentalsResult, HistoryResult, QuoteResult
+
+logger = logging.getLogger(__name__)
+
+_PROVIDERS_FILE = Path.home() / ".arthera" / "providers.json"
+_BASE = "https://finnhub.io/api/v1"
+
+
+def _read_finnhub_key() -> str:
+    try:
+        import os
+        env = os.getenv("FINNHUB_API_KEY", "") or os.getenv("FINNHUB_KEY", "")
+        if env:
+            return env
+        if _PROVIDERS_FILE.exists():
+            raw = json.loads(_PROVIDERS_FILE.read_text(encoding="utf-8"))
+            key = raw.get("data", {}).get("finnhub", {}).get("api_key", "")
+            if key:
+                return key
+    except Exception:
+        pass
+    return ""
+
+
+def _fh_get(path: str, key: str, params: dict = None, timeout: int = 8) -> dict:
+    qs = "&".join(f"{k}={v}" for k, v in (params or {}).items())
+    url = f"{_BASE}{path}?token={key}" + (f"&{qs}" if qs else "")
+    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.loads(r.read())
+
+
+class FinnhubSource(BaseDataSource):
+
+    name         = "finnhub"
+    markets      = ["us", "hk", "crypto"]
+    requires_key = True
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        self._key = _read_finnhub_key()
+
+    def is_configured(self) -> bool:
+        return bool(self._key)
+
+    # ── Quote ─────────────────────────────────────────────────────────────────
+
+    def quote(self, symbol: str) -> Optional[QuoteResult]:
+        if not self._key:
+            return None
+        sym = symbol.upper().replace(".HK", "")
+        try:
+            data = _fh_get("/quote", self._key, {"symbol": sym})
+            price = float(data.get("c") or 0)
+            if price <= 0:
+                return None
+            prev = float(data.get("pc") or price)
+            chg_pct = round((price - prev) / prev * 100, 2) if prev else 0
+
+            # Extra: company profile for name / market cap
+            name = sym
+            mkt_cap = 0.0
+            currency = "USD"
+            try:
+                prof = _fh_get("/stock/profile2", self._key, {"symbol": sym})
+                name = prof.get("name") or sym
+                mkt_cap = float(prof.get("marketCapitalization") or 0) * 1e6
+                currency = prof.get("currency") or "USD"
+            except Exception:
+                pass
+
+            return QuoteResult(
+                symbol     = symbol,
+                name       = name,
+                price      = price,
+                change     = round(price - prev, 4),
+                change_pct = chg_pct,
+                volume     = float(data.get("v") or 0),
+                high_52w   = float(data.get("h") or 0),
+                low_52w    = float(data.get("l") or 0),
+                market_cap = mkt_cap,
+                currency   = currency,
+                market     = "us",
+                source     = self.name,
+            )
+        except Exception as e:
+            logger.debug(f"[finnhub] quote({symbol}) 失败: {e}")
+            return None
+
+    # ── History ───────────────────────────────────────────────────────────────
+
+    def history(self, symbol: str, days: int = 90, interval: str = "1d") -> Optional[HistoryResult]:
+        if not self._key:
+            return None
+        sym = symbol.upper()
+        resolution = "D" if interval in ("1d", "day", "daily") else "60"
+        _end   = int(time.time())
+        _start = int((datetime.now() - timedelta(days=days + 5)).timestamp())
+        try:
+            data = _fh_get("/stock/candle", self._key, {
+                "symbol": sym, "resolution": resolution,
+                "from": _start, "to": _end,
+            })
+            if data.get("s") != "ok":
+                return None
+            t = data.get("t", [])
+            o = data.get("o", [])
+            h = data.get("h", [])
+            l = data.get("l", [])
+            c = data.get("c", [])
+            v = data.get("v", [])
+            if not c:
+                return None
+            df = pd.DataFrame({
+                "日期":  [datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d") for ts in t],
+                "开盘":  o, "最高": h, "最低": l, "收盘": c, "成交量": v,
+            })
+            df.index = pd.to_datetime(df["日期"])
+            # Also add English column aliases for DataService compatibility
+            df["Open"]   = df["开盘"]
+            df["High"]   = df["最高"]
+            df["Low"]    = df["最低"]
+            df["Close"]  = df["收盘"]
+            df["Volume"] = df["成交量"]
+            return HistoryResult(symbol=symbol, data=df, source=self.name, interval=interval)
+        except Exception as e:
+            logger.debug(f"[finnhub] history({symbol}) 失败: {e}")
+            return None
+
+    # ── Fundamentals ──────────────────────────────────────────────────────────
+
+    def fundamentals(self, symbol: str) -> Optional[FundamentalsResult]:
+        if not self._key:
+            return None
+        sym = symbol.upper()
+        try:
+            # Basic financials (PE, market cap, etc.)
+            metrics_data = _fh_get("/stock/metric", self._key, {"symbol": sym, "metric": "all"})
+            m = metrics_data.get("metric") or {}
+
+            def _mf(key: str) -> Optional[float]:
+                v = m.get(key)
+                if v is None:
+                    return None
+                try:
+                    fv = float(v)
+                    return None if (math.isnan(fv) or fv == 0) else fv
+                except (TypeError, ValueError):
+                    return None
+
+            pe   = _mf("peTTM") or _mf("peExclExtraItemsTTM")
+            pb   = _mf("pbAnnual") or _mf("pbQuarterly")
+            roe  = _mf("roeTTM") or _mf("roeAnnual")
+            div_yield = _mf("dividendYieldIndicatedAnnual")
+            rev_growth = _mf("revenueGrowthTTMYoy")
+            eps_growth = _mf("epsGrowthTTMYoy")
+            mktcap_raw = _mf("marketCapitalization")
+            total_mv = (mktcap_raw * 1e6) if mktcap_raw else None
+
+            if pe is None and pb is None and roe is None:
+                return None
+
+            return FundamentalsResult(
+                symbol         = symbol,
+                pe_ttm         = pe,
+                pb             = pb,
+                roe            = roe,
+                revenue_growth = rev_growth,
+                net_profit_growth = eps_growth,
+                dividend_yield = div_yield,
+                total_mv       = total_mv,
+                source         = self.name,
+            )
+        except Exception as e:
+            logger.debug(f"[finnhub] fundamentals({symbol}) 失败: {e}")
+            return None