@drico2008/fincli 0.1.9 → 0.2.2

package/fincli/app/providers/market/custom_provider.py

@@ -1,169 +1,186 @@
-"""Custom HTTP market API provider.
-
-Expected endpoint contract:
-- GET /quote/{symbol}
-- GET /history/{symbol}?period=6mo&interval=1d
-- GET /news/{symbol}?limit=5
-- GET /fundamentals/{symbol}
-
-The provider accepts common JSON key variants so users can adapt simple APIs
-without changing FinCLI core.
-"""
-
-from __future__ import annotations
-
-from datetime import datetime
-from typing import Any
-
-import httpx
-
-from fincli.app.providers.market.base import (
-    BaseMarketProvider,
-    Candle,
-    FundamentalSnapshot,
-    NewsItem,
-    ProviderStatus,
-    Quote,
-)
-from fincli.app.utils.errors import ProviderError, RateLimitError
-
-
-class CustomMarketProvider(BaseMarketProvider):
-    name = "custom"
-
-    def __init__(
-        self,
-        api_key: str | None,
-        base_url: str,
-        client: httpx.AsyncClient | None = None,
-    ) -> None:
-        self.api_key = api_key or ""
-        self.base_url = base_url.rstrip("/")
-        self._client = client
-
-    async def quote(self, symbol: str) -> Quote:
-        data = await self._get(f"/quote/{symbol.upper()}")
-        return Quote(
-            symbol=str(data.get("symbol") or symbol).upper(),
-            price=_safe_float(data.get("price") or data.get("last") or data.get("last_price")),
-            currency=str(data.get("currency") or "USD"),
-            provider=self.name,
-            timestamp=_parse_datetime(data.get("timestamp")) or datetime.now(),
-            status=str(data.get("status") or "custom"),
-        )
-
-    async def history(self, symbol: str, period: str = "6mo", interval: str = "1d") -> list[Candle]:
-        data = await self._get(f"/history/{symbol.upper()}", params={"period": period, "interval": interval})
-        raw_items = data.get("candles") if isinstance(data, dict) else data
-        if not isinstance(raw_items, list):
-            raise ProviderError("Response history custom provider tidak valid.")
-        candles: list[Candle] = []
-        for item in raw_items:
-            if not isinstance(item, dict):
-                continue
-            candles.append(
-                Candle(
-                    timestamp=_parse_datetime(item.get("timestamp") or item.get("date")) or datetime.now(),
-                    open=float(item.get("open") or item.get("o")),
-                    high=float(item.get("high") or item.get("h")),
-                    low=float(item.get("low") or item.get("l")),
-                    close=float(item.get("close") or item.get("c")),
-                    volume=float(item.get("volume") or item.get("v") or 0),
-                )
-            )
-        if not candles:
-            raise ProviderError(f"Data OHLCV kosong untuk {symbol}.")
-        return candles
-
-    async def news(self, symbol: str, limit: int = 5) -> list[NewsItem]:
-        data = await self._get(f"/news/{symbol.upper()}", params={"limit": limit})
-        raw_items = data.get("news") if isinstance(data, dict) else data
-        if not isinstance(raw_items, list):
-            raise ProviderError("Response news custom provider tidak valid.")
-        items: list[NewsItem] = []
-        for item in raw_items[:limit]:
-            if not isinstance(item, dict):
-                continue
-            items.append(
-                NewsItem(
-                    title=str(item.get("title") or "Untitled"),
-                    source=str(item.get("source") or self.name),
-                    url=item.get("url"),
-                    published_at=_parse_datetime(item.get("published_at") or item.get("timestamp")),
-                    summary=str(item.get("summary") or ""),
-                )
-            )
-        return items
-
-    async def fundamentals(self, symbol: str) -> FundamentalSnapshot:
-        data = await self._get(f"/fundamentals/{symbol.upper()}")
-        return FundamentalSnapshot(
-            symbol=str(data.get("symbol") or symbol).upper(),
-            provider=self.name,
-            currency=str(data.get("currency") or "USD"),
-            market_cap=_safe_float(data.get("market_cap") or data.get("marketCap")),
-            pe_ratio=_safe_float(data.get("pe_ratio") or data.get("trailingPE")),
-            eps=_safe_float(data.get("eps") or data.get("trailingEps")),
-            revenue=_safe_float(data.get("revenue") or data.get("totalRevenue")),
-            beta=_safe_float(data.get("beta")),
-            sector=data.get("sector"),
-            industry=data.get("industry"),
-        )
-
-    async def status(self) -> ProviderStatus:
-        status = "configured" if self.api_key else "unavailable"
-        message = "Custom provider configured." if self.api_key else "Requires MARKET_DATA_API_KEY."
-        return ProviderStatus(name=self.name, realtime=True, status=status, message=message)
-
-    async def _get(self, path: str, params: dict[str, object] | None = None) -> Any:
-        if not self.api_key:
-            raise ProviderError(
-                "API key custom market provider belum diatur.",
-                "Gunakan /news_model key custom <api_key> <base_url>.",
-            )
-        if not self.base_url:
-            raise ProviderError(
-                "Base URL custom market provider belum diatur.",
-                "Gunakan /news_model key custom <api_key> <base_url>.",
-            )
-
-        close_client = self._client is None
-        client = self._client or httpx.AsyncClient(timeout=30)
-        headers = {"X-API-Key": self.api_key, "Authorization": f"Bearer {self.api_key}"}
-        try:
-            response = await client.get(f"{self.base_url}{path}", params=params, headers=headers)
-            if response.status_code == 429:
-                raise RateLimitError("Custom market provider terkena rate limit.")
-            response.raise_for_status()
-            return response.json()
-        except httpx.TimeoutException as exc:
-            raise ProviderError("Custom market provider timeout.") from exc
-        except httpx.HTTPStatusError as exc:
-            raise ProviderError(f"Custom market provider gagal: HTTP {exc.response.status_code}.") from exc
-        except ValueError as exc:
-            raise ProviderError("Response custom market provider bukan JSON valid.") from exc
-        finally:
-            if close_client:
-                await client.aclose()
-
-
-def _safe_float(value: Any) -> float | None:
-    try:
-        if value is None:
-            return None
-        return float(value)
-    except (TypeError, ValueError):
-        return None
-
-
-def _parse_datetime(value: Any) -> datetime | None:
-    if value is None:
-        return None
-    if isinstance(value, (int, float)):
-        return datetime.fromtimestamp(value)
-    if isinstance(value, str):
-        try:
-            return datetime.fromisoformat(value.replace("Z", "+00:00"))
-        except ValueError:
-            return None
-    return None
+"""Custom HTTP market API provider.
+
+Expected endpoint contract:
+- GET /quote/{symbol}
+- GET /history/{symbol}?period=6mo&interval=1d
+- GET /news/{symbol}?limit=5
+- GET /fundamentals/{symbol}
+
+The provider accepts common JSON key variants so users can adapt simple APIs
+without changing FinCLI core.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from fincli.app.providers.market.base import (
+    BaseMarketProvider,
+    Candle,
+    FundamentalSnapshot,
+    NewsItem,
+    ProviderStatus,
+    Quote,
+)
+from fincli.app.utils.errors import ProviderError, RateLimitError
+
+
+class CustomMarketProvider(BaseMarketProvider):
+    name = "custom"
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key or ""
+        self.base_url = base_url.rstrip("/")
+        self._client = client
+
+    async def quote(self, symbol: str) -> Quote:
+        data = await self._get(f"/quote/{symbol.upper()}")
+        data = _require_mapping(data, "quote")
+        price = _required_float(data.get("price") or data.get("last") or data.get("last_price"), "quote.price")
+        return Quote(
+            symbol=str(data.get("symbol") or symbol).upper(),
+            price=price,
+            currency=str(data.get("currency") or "USD"),
+            provider=self.name,
+            timestamp=_parse_datetime(data.get("timestamp")) or datetime.now(),
+            status=str(data.get("status") or "custom"),
+        )
+
+    async def history(self, symbol: str, period: str = "6mo", interval: str = "1d") -> list[Candle]:
+        data = await self._get(f"/history/{symbol.upper()}", params={"period": period, "interval": interval})
+        raw_items = data.get("candles") if isinstance(data, dict) else data
+        if not isinstance(raw_items, list):
+            raise ProviderError("Response history custom provider tidak valid.")
+        candles: list[Candle] = []
+        for item in raw_items:
+            if not isinstance(item, dict):
+                continue
+            candles.append(
+                Candle(
+                    timestamp=_parse_datetime(item.get("timestamp") or item.get("date")) or datetime.now(),
+                    open=_required_float(item.get("open") or item.get("o"), "history.open"),
+                    high=_required_float(item.get("high") or item.get("h"), "history.high"),
+                    low=_required_float(item.get("low") or item.get("l"), "history.low"),
+                    close=_required_float(item.get("close") or item.get("c"), "history.close"),
+                    volume=float(item.get("volume") or item.get("v") or 0),
+                )
+            )
+        if not candles:
+            raise ProviderError(f"Data OHLCV kosong untuk {symbol}.")
+        return candles
+
+    async def news(self, symbol: str, limit: int = 5) -> list[NewsItem]:
+        data = await self._get(f"/news/{symbol.upper()}", params={"limit": limit})
+        raw_items = data.get("news") if isinstance(data, dict) else data
+        if not isinstance(raw_items, list):
+            raise ProviderError("Response news custom provider tidak valid.")
+        items: list[NewsItem] = []
+        for item in raw_items[:limit]:
+            if not isinstance(item, dict):
+                continue
+            items.append(
+                NewsItem(
+                    title=str(item.get("title") or "Untitled"),
+                    source=str(item.get("source") or self.name),
+                    url=item.get("url"),
+                    published_at=_parse_datetime(item.get("published_at") or item.get("timestamp")),
+                    summary=str(item.get("summary") or ""),
+                )
+            )
+        return items
+
+    async def fundamentals(self, symbol: str) -> FundamentalSnapshot:
+        data = await self._get(f"/fundamentals/{symbol.upper()}")
+        data = _require_mapping(data, "fundamentals")
+        return FundamentalSnapshot(
+            symbol=str(data.get("symbol") or symbol).upper(),
+            provider=self.name,
+            currency=str(data.get("currency") or "USD"),
+            market_cap=_safe_float(data.get("market_cap") or data.get("marketCap")),
+            pe_ratio=_safe_float(data.get("pe_ratio") or data.get("trailingPE")),
+            eps=_safe_float(data.get("eps") or data.get("trailingEps")),
+            revenue=_safe_float(data.get("revenue") or data.get("totalRevenue")),
+            beta=_safe_float(data.get("beta")),
+            sector=data.get("sector"),
+            industry=data.get("industry"),
+        )
+
+    async def status(self) -> ProviderStatus:
+        status = "configured" if self.api_key else "unavailable"
+        message = "Custom provider configured." if self.api_key else "Requires MARKET_DATA_API_KEY."
+        return ProviderStatus(name=self.name, realtime=True, status=status, message=message)
+
+    async def _get(self, path: str, params: dict[str, object] | None = None) -> Any:
+        if not self.api_key:
+            raise ProviderError(
+                "API key custom market provider belum diatur.",
+                "Gunakan /news_model key custom <api_key> <base_url>.",
+            )
+        if not self.base_url:
+            raise ProviderError(
+                "Base URL custom market provider belum diatur.",
+                "Gunakan /news_model key custom <api_key> <base_url>.",
+            )
+
+        close_client = self._client is None
+        client = self._client or httpx.AsyncClient(timeout=30)
+        headers = {"X-API-Key": self.api_key, "Authorization": f"Bearer {self.api_key}"}
+        try:
+            response = await client.get(f"{self.base_url}{path}", params=params, headers=headers)
+            if response.status_code == 429:
+                raise RateLimitError("Custom market provider terkena rate limit.")
+            response.raise_for_status()
+            data = response.json()
+            return data
+        except httpx.TimeoutException as exc:
+            raise ProviderError("Custom market provider timeout.") from exc
+        except httpx.HTTPStatusError as exc:
+            raise ProviderError(f"Custom market provider gagal: HTTP {exc.response.status_code}.") from exc
+        except ValueError as exc:
+            raise ProviderError("Response custom market provider bukan JSON valid.") from exc
+        finally:
+            if close_client:
+                await client.aclose()
+
+
+def _safe_float(value: Any) -> float | None:
+    try:
+        if value is None:
+            return None
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _required_float(value: Any, field_name: str) -> float:
+    number = _safe_float(value)
+    if number is None:
+        raise ProviderError(f"Response custom provider tidak valid: {field_name} wajib berupa angka.")
+    return number
+
+
+def _require_mapping(value: Any, section: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ProviderError(f"Response {section} custom provider tidak valid: root JSON harus object.")
+    return value
+
+
+def _parse_datetime(value: Any) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value)
+    if isinstance(value, str):
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+    return None

package/fincli/app/providers/market/manager.py

@@ -5,7 +5,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 import os
 
-from fincli.app.providers.market.base import BaseMarketProvider
+from fincli.app.providers.market.base import BaseMarketProvider, ProviderEntitlement
+from fincli.app.providers.market.alphavantage_provider import AlphaVantageProvider
 from fincli.app.providers.market.custom_provider import CustomMarketProvider
 from fincli.app.providers.market.finnhub_provider import FinnhubProvider
 from fincli.app.providers.market.twelvedata_provider import TwelveDataProvider
@@ -46,6 +47,12 @@ MARKET_PROVIDERS: dict[str, MarketProviderInfo] = {
         status="configured",
         notes="Multi-asset provider for stocks, forex, ETFs, indices, commodities, and crypto. Requires TWELVE_DATA_API_KEY.",
     ),
+    "alphavantage": MarketProviderInfo(
+        name="alphavantage",
+        realtime=False,
+        status="configured",
+        notes="Alpha Vantage adapter for stocks, FX, news sentiment, and company overview. Requires ALPHA_VANTAGE_API_KEY.",
+    ),
 }
 
 
@@ -71,6 +78,8 @@ class MarketProviderManager:
             return FinnhubProvider(api_key=os.getenv("FINNHUB_API_KEY"))
         if provider_name == "twelvedata":
             return TwelveDataProvider(api_key=os.getenv("TWELVE_DATA_API_KEY"))
+        if provider_name == "alphavantage":
+            return AlphaVantageProvider(api_key=os.getenv("ALPHA_VANTAGE_API_KEY"))
         raise ValueError(f"Market provider tidak dikenal: {name}")
 
     def create_many(self, names: list[str]) -> list[BaseMarketProvider]:
@@ -113,6 +122,80 @@ class MarketProviderManager:
                 "status": _mask_status(os.getenv("TWELVE_DATA_API_KEY")),
                 "source": secret_source("TWELVE_DATA_API_KEY"),
             },
+            {
+                "provider": "alphavantage",
+                "key": "ALPHA_VANTAGE_API_KEY",
+                "status": _mask_status(os.getenv("ALPHA_VANTAGE_API_KEY")),
+                "source": secret_source("ALPHA_VANTAGE_API_KEY"),
+            },
+        ]
+
+    def entitlements(self) -> list[ProviderEntitlement]:
+        return [
+            ProviderEntitlement(
+                provider="yfinance",
+                status="available",
+                realtime_label="delayed/fallback",
+                asset_classes=("stocks", "ETFs", "indices", "forex", "crypto", "commodities", "funds"),
+                capabilities=("quote", "history", "news", "fundamentals", "yahoo tables"),
+                limitations=(
+                    "No API key required.",
+                    "Data may be delayed and Yahoo coverage varies by exchange.",
+                    "Not suitable for guaranteed realtime execution workflows.",
+                ),
+            ),
+            ProviderEntitlement(
+                provider="twelvedata",
+                status="configured" if os.getenv("TWELVE_DATA_API_KEY") else "missing key",
+                realtime_label="plan-dependent",
+                asset_classes=("stocks", "ETFs", "indices", "forex", "crypto", "commodities"),
+                capabilities=("quote", "history"),
+                limitations=(
+                    "Requires TWELVE_DATA_API_KEY.",
+                    "Realtime access depends on plan and exchange entitlement.",
+                    "News/fundamentals are not implemented in this adapter yet.",
+                ),
+            ),
+            ProviderEntitlement(
+                provider="finnhub",
+                status="configured" if os.getenv("FINNHUB_API_KEY") else "missing key",
+                realtime_label="plan-dependent",
+                asset_classes=("stocks", "forex", "crypto"),
+                capabilities=("quote", "history", "news", "fundamentals", "economic calendar"),
+                limitations=(
+                    "Requires FINNHUB_API_KEY.",
+                    "Forex/crypto support is strongest for candles.",
+                    "News/fundamentals coverage is strongest for equities.",
+                ),
+            ),
+            ProviderEntitlement(
+                provider="custom",
+                status=(
+                    "configured"
+                    if os.getenv("MARKET_DATA_API_KEY") and os.getenv("MARKET_DATA_BASE_URL")
+                    else "missing key/base url"
+                ),
+                realtime_label="custom",
+                asset_classes=("provider-defined",),
+                capabilities=("quote", "history", "news", "fundamentals"),
+                limitations=(
+                    "Requires MARKET_DATA_API_KEY and MARKET_DATA_BASE_URL.",
+                    "Realtime/delayed status must be supplied by the custom API payload.",
+                    "Payloads are validated by FinCLI before being accepted.",
+                ),
+            ),
+            ProviderEntitlement(
+                provider="alphavantage",
+                status="configured" if os.getenv("ALPHA_VANTAGE_API_KEY") else "missing key",
+                realtime_label="delayed/plan-dependent",
+                asset_classes=("stocks", "forex", "selected crypto/commodities via provider functions"),
+                capabilities=("quote", "history", "news", "fundamentals"),
+                limitations=(
+                    "Requires ALPHA_VANTAGE_API_KEY.",
+                    "Free plans are heavily rate-limited.",
+                    "Realtime availability and exchange coverage depend on Alpha Vantage plan.",
+                ),
+            ),
         ]
 
 

package/fincli/app/providers/market/symbols.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from fincli.app.providers.market.base import SymbolSearchResult
+
 
 FOREX_CURRENCIES = {
     "AUD",
@@ -129,6 +131,45 @@ class ResolvedSymbol:
     asset_class: str
 
 
+@dataclass(frozen=True, slots=True)
+class SymbolAlias:
+    symbol: str
+    name: str
+    asset_class: str
+    exchange: str = ""
+    currency: str = ""
+    aliases: tuple[str, ...] = ()
+    notes: str = ""
+
+
+SYMBOL_CATALOG: tuple[SymbolAlias, ...] = (
+    SymbolAlias("AAPL", "Apple Inc.", "stock", "NASDAQ", "USD", ("APPLE",)),
+    SymbolAlias("MSFT", "Microsoft Corporation", "stock", "NASDAQ", "USD", ("MICROSOFT",)),
+    SymbolAlias("NVDA", "NVIDIA Corporation", "stock", "NASDAQ", "USD", ("NVIDIA",)),
+    SymbolAlias("TSLA", "Tesla Inc.", "stock", "NASDAQ", "USD", ("TESLA",)),
+    SymbolAlias("SPY", "SPDR S&P 500 ETF Trust", "etf", "NYSE Arca", "USD", ("S&P ETF",)),
+    SymbolAlias("QQQ", "Invesco QQQ Trust", "etf", "NASDAQ", "USD", ("NASDAQ ETF",)),
+    SymbolAlias("SPX", "S&P 500 Index", "index", "US", "USD", ("SP500", "S&P500", "^GSPC")),
+    SymbolAlias("NASDAQ", "Nasdaq Composite Index", "index", "US", "USD", ("IXIC", "^IXIC")),
+    SymbolAlias("DOW", "Dow Jones Industrial Average", "index", "US", "USD", ("DJI", "^DJI")),
+    SymbolAlias("DAX", "DAX Performance Index", "index", "Germany", "EUR", ("^GDAXI",)),
+    SymbolAlias("NIKKEI", "Nikkei 225 Index", "index", "Japan", "JPY", ("N225", "^N225")),
+    SymbolAlias("EURUSD", "Euro / US Dollar", "forex", "FX", "USD", ("EUR/USD", "EURUSD=X")),
+    SymbolAlias("GBPUSD", "British Pound / US Dollar", "forex", "FX", "USD", ("GBP/USD", "GBPUSD=X")),
+    SymbolAlias("USDJPY", "US Dollar / Japanese Yen", "forex", "FX", "JPY", ("USD/JPY", "USDJPY=X")),
+    SymbolAlias("XAUUSD", "Gold Spot / US Dollar", "commodity", "Metals", "USD", ("GOLD", "XAU/USD", "GC=F")),
+    SymbolAlias("XAGUSD", "Silver Spot / US Dollar", "commodity", "Metals", "USD", ("SILVER", "XAG/USD", "SI=F")),
+    SymbolAlias("WTI", "WTI Crude Oil Futures", "commodity", "NYMEX", "USD", ("CL=F", "OIL")),
+    SymbolAlias("BRENT", "Brent Crude Oil Futures", "commodity", "ICE", "USD", ("BZ=F",)),
+    SymbolAlias("BTC-USD", "Bitcoin / US Dollar", "crypto", "Crypto", "USD", ("BTCUSD", "BTCUSDT", "BINANCE:BTCUSDT")),
+    SymbolAlias("ETH-USD", "Ethereum / US Dollar", "crypto", "Crypto", "USD", ("ETHUSD", "ETHUSDT", "BINANCE:ETHUSDT")),
+    SymbolAlias("BBRI", "Bank Rakyat Indonesia", "stock", "IDX", "IDR", ("BBRI.JK",)),
+    SymbolAlias("BBCA", "Bank Central Asia", "stock", "IDX", "IDR", ("BBCA.JK",)),
+    SymbolAlias("BMRI", "Bank Mandiri", "stock", "IDX", "IDR", ("BMRI.JK",)),
+    SymbolAlias("TLKM", "Telkom Indonesia", "stock", "IDX", "IDR", ("TLKM.JK",)),
+)
+
+
 def resolve_yfinance_symbol(symbol: str) -> ResolvedSymbol:
     normalized = _normalize(symbol)
     if normalized in YFINANCE_ALIASES:
@@ -153,6 +194,8 @@ def resolve_twelvedata_symbol(symbol: str) -> ResolvedSymbol:
 
 def resolve_finnhub_symbol(symbol: str) -> ResolvedSymbol:
     normalized = _normalize(symbol)
+    if _is_metal_pair(normalized):
+        return ResolvedSymbol(symbol, f"OANDA:{normalized[:3]}_{normalized[3:]}", "commodity")
     if _is_forex_pair(normalized):
         return ResolvedSymbol(symbol, f"OANDA:{normalized[:3]}_{normalized[3:]}", "forex")
     if normalized.startswith("BINANCE:"):
@@ -162,6 +205,68 @@ def resolve_finnhub_symbol(symbol: str) -> ResolvedSymbol:
     return ResolvedSymbol(symbol, symbol.upper(), "stock")
 
 
+def resolve_provider_symbol(provider: str, symbol: str) -> ResolvedSymbol:
+    provider_name = provider.lower().strip()
+    if provider_name == "yfinance":
+        return resolve_yfinance_symbol(symbol)
+    if provider_name == "twelvedata":
+        return resolve_twelvedata_symbol(symbol)
+    if provider_name == "finnhub":
+        return resolve_finnhub_symbol(symbol)
+    if provider_name == "alphavantage":
+        normalized = _normalize(symbol)
+        if _is_metal_pair(normalized):
+            return ResolvedSymbol(symbol, normalized, "commodity")
+        if _is_forex_pair(normalized):
+            return ResolvedSymbol(symbol, normalized, "forex")
+        if normalized in IDX_ALIASES:
+            return ResolvedSymbol(symbol, normalized, "stock")
+        return ResolvedSymbol(symbol, symbol.strip().upper(), _infer_asset_class(normalized))
+    if provider_name == "custom":
+        normalized = symbol.strip().upper()
+        return ResolvedSymbol(symbol, normalized, _infer_asset_class(normalized))
+    raise ValueError(f"Unknown market provider: {provider}")
+
+
+def provider_symbol_matrix(symbol: str, providers: tuple[str, ...] | None = None) -> dict[str, ResolvedSymbol]:
+    names = providers or ("yfinance", "twelvedata", "finnhub", "alphavantage", "custom")
+    return {name: resolve_provider_symbol(name, symbol) for name in names}
+
+
+def search_symbol_catalog(query: str, limit: int = 12) -> list[SymbolSearchResult]:
+    normalized = _normalize(query)
+    if not normalized:
+        return []
+
+    matches: list[tuple[int, SymbolAlias]] = []
+    for item in SYMBOL_CATALOG:
+        haystack = [item.symbol, item.name, item.asset_class, item.exchange, item.currency, *item.aliases]
+        normalized_haystack = [_normalize(part) for part in haystack if part]
+        score = _match_score(normalized, normalized_haystack)
+        if score > 0:
+            matches.append((score, item))
+
+    matches.sort(key=lambda pair: (-pair[0], pair[1].symbol))
+    results = [_symbol_alias_to_result(item) for _, item in matches[:limit]]
+    if results:
+        return results
+
+    guessed = symbol_search_result(query)
+    return [guessed] if guessed else []
+
+
+def symbol_search_result(symbol: str) -> SymbolSearchResult:
+    matrix = provider_symbol_matrix(symbol)
+    first = next(iter(matrix.values()))
+    return SymbolSearchResult(
+        symbol=symbol.upper(),
+        name=f"{symbol.upper()} (inferred)",
+        asset_class=first.asset_class,
+        provider_symbols={provider: resolved.symbol for provider, resolved in matrix.items()},
+        notes="Inferred from symbol pattern. Verify exchange/provider entitlement before relying on it.",
+    )
+
+
 def _normalize(symbol: str) -> str:
     return symbol.strip().upper().replace(" ", "").replace("-", "").replace("_", "").replace("/", "")
 
@@ -180,3 +285,41 @@ def _alias_class(symbol: str) -> str:
     if symbol.startswith("XAU") or symbol.startswith("XAG"):
         return "commodity"
     return "index"
+
+
+def _symbol_alias_to_result(item: SymbolAlias) -> SymbolSearchResult:
+    matrix = provider_symbol_matrix(item.symbol)
+    return SymbolSearchResult(
+        symbol=item.symbol,
+        name=item.name,
+        asset_class=item.asset_class,
+        exchange=item.exchange,
+        currency=item.currency,
+        provider_symbols={provider: resolved.symbol for provider, resolved in matrix.items()},
+        notes=item.notes,
+    )
+
+
+def _match_score(query: str, haystack: list[str]) -> int:
+    score = 0
+    for value in haystack:
+        if value == query:
+            score = max(score, 100)
+        elif value.startswith(query):
+            score = max(score, 80)
+        elif query in value:
+            score = max(score, 50)
+    return score
+
+
+def _infer_asset_class(symbol: str) -> str:
+    normalized = _normalize(symbol)
+    if _is_metal_pair(normalized):
+        return "commodity"
+    if _is_forex_pair(normalized):
+        return "forex"
+    if normalized.endswith("USDT") or normalized.endswith("USD") and normalized[:3] in {"BTC", "ETH", "SOL", "BNB"}:
+        return "crypto"
+    if normalized.startswith("^") or normalized in YFINANCE_ALIASES:
+        return "index"
+    return "stock"