cyberagent 0.1.0__py3-none-any.whl

cyberagent/__init__.py

@@ -0,0 +1,40 @@
+"""cyberagent — TradingAgents for every market.
+
+A 5-department LLM analyst chain unified across stocks (A-share / HK / US) and
+crypto (token / contract address). The analytical soul is a physical-bottleneck
+reverse-consensus 5-step chain. Bring your own LLM key.
+
+    from cyberagent import AnalystChain
+
+    chain = AnalystChain(llm="gemini", api_key="...", lang="zh")
+    report = await chain.analyze("NVDA")
+    print(report.final_decision, report.confidence)
+    print(report.departments["industry"].markdown)
+
+Public API:
+    AnalystChain     — main entry, await chain.analyze(symbol)
+    AssetClassifier  — unified routing for A-share / HK / US / crypto / EVM
+    classify         — functional form of the classifier
+    LLMAdapter       — OpenAI / Gemini / Claude / DeepSeek + custom
+    MockLLM          — offline adapter for tests/examples
+    AnalystReport / DeptReport / AssetInfo — Pydantic structured output
+"""
+
+from .chain import AnalystChain
+from .classifier import AssetClassifier, classify
+from .llm_adapter import LLMAdapter, MockLLM
+from .models import AnalystReport, AssetInfo, DeptReport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "AnalystChain",
+    "AssetClassifier",
+    "classify",
+    "LLMAdapter",
+    "MockLLM",
+    "AnalystReport",
+    "DeptReport",
+    "AssetInfo",
+]

cyberagent/adapters/__init__.py

@@ -0,0 +1,31 @@
+"""Data adapters — route an AssetInfo to the right source and return a markdown
+data block the departments can read.
+
+    fetch(asset_info) -> (data_md, meta)
+
+All adapters degrade gracefully: on missing libs / no network / errors they
+return ("", {"company_name": code}) so the analyst chain still runs on LLM
+reasoning alone.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+from ..models import AssetInfo
+from . import crypto, stock
+
+__all__ = ["fetch", "crypto", "stock"]
+
+
+async def fetch(asset_info: AssetInfo, *, timeout: float = 10.0) -> Tuple[str, dict]:
+    """Return (data_md, meta) for an asset. meta always has 'company_name'."""
+    t = asset_info.type
+    try:
+        if t in ("token", "evm_contract", "solana_contract"):
+            return await crypto.fetch(asset_info, timeout=timeout)
+        if t in ("stock_cn", "stock_us", "stock_hk"):
+            return await stock.fetch(asset_info, timeout=timeout)
+    except Exception:
+        pass
+    return "", {"company_name": asset_info.code}

cyberagent/adapters/crypto.py

@@ -0,0 +1,96 @@
+"""Crypto data adapter — CoinGecko (no key, free tier).
+
+Returns a markdown data block for a token. Network/errors degrade gracefully to
+("", {"company_name": code}) so the chain can still run on LLM reasoning alone.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+from ..models import AssetInfo
+
+_CG = "https://api.coingecko.com/api/v3"
+
+
+async def fetch(asset_info: AssetInfo, *, timeout: float = 10.0) -> Tuple[str, dict]:
+    code = asset_info.code
+    cgid = asset_info.coingecko_id
+    meta = {"company_name": code}
+
+    if asset_info.type in ("evm_contract", "solana_contract"):
+        md = (
+            f"### On-chain asset\n- Address: {code}\n- Chain: {asset_info.chain}\n"
+            "- No token summary available without an indexer; rely on reasoning + search.\n"
+        )
+        return md, meta
+
+    try:
+        import httpx
+    except ImportError:
+        return "", meta
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            if not cgid:
+                r = await client.get(f"{_CG}/search", params={"query": code})
+                coins = (r.json() or {}).get("coins", [])
+                if coins:
+                    cgid = coins[0]["id"]
+            if not cgid:
+                return "", meta
+            r = await client.get(
+                f"{_CG}/coins/{cgid}",
+                params={"localization": "false", "tickers": "false", "market_data": "true",
+                        "community_data": "false", "developer_data": "false", "sparkline": "false"},
+            )
+            d = r.json() or {}
+    except Exception:
+        return "", meta
+
+    name = d.get("name") or code
+    meta["company_name"] = name
+    m = d.get("market_data") or {}
+
+    def usd(block):
+        return (m.get(block) or {}).get("usd")
+
+    desc = ((d.get("description") or {}).get("en") or "").strip().replace("\n", " ")[:400]
+    cats = ", ".join([c for c in (d.get("categories") or []) if c][:6])
+
+    chg24 = m.get("price_change_percentage_24h")
+    chg7 = m.get("price_change_percentage_7d")
+    chg30 = m.get("price_change_percentage_30d")
+    ath_chg = (m.get("ath_change_percentage") or {}).get("usd")
+    flags = []
+    try:
+        if chg24 is not None and chg24 >= 20: flags.append(f"24h {chg24:+.0f}%")
+        if chg7 is not None and chg7 >= 40: flags.append(f"7d {chg7:+.0f}%")
+        if chg30 is not None and chg30 >= 80: flags.append(f"30d {chg30:+.0f}%")
+        if ath_chg is not None and ath_chg >= -8: flags.append("near all-time high")
+    except Exception:
+        pass
+    flag_md = ""
+    if flags:
+        flag_md = ("- ⚠ **PARABOLIC / NARRATIVE-MOVE FLAG**: " + "; ".join(flags) +
+                   ". You MUST search WHY (catalyst / listing / KOL / unlock) and treat a "
+                   "headline-driven spike as an AVOID/observe form, not a buy form.\n")
+    meta["price_flags"] = flags
+
+    md = (
+        f"### Token: {name} ({(d.get('symbol') or '').upper()})\n"
+        f"- Narrative / categories: {cats or 'N/A'}\n"
+        f"- Price (USD): {usd('current_price')}\n"
+        f"- Market cap (USD): {usd('market_cap')}\n"
+        f"- Fully diluted valuation (USD): {usd('fully_diluted_valuation')}\n"
+        f"- 24h volume (USD): {usd('total_volume')}\n"
+        f"\n#### Price action (CHECK BEFORE THESIS)\n"
+        f"- 24h / 7d / 30d change %: {chg24} / {chg7} / {chg30}\n"
+        f"- ATH (USD): {usd('ath')} | from ATH %: {ath_chg}\n"
+        f"{flag_md}"
+        f"\n#### Supply\n"
+        f"- Circulating: {m.get('circulating_supply')} | Total: {m.get('total_supply')} | Max: {m.get('max_supply')}\n"
+        f"\n#### Description\n{desc or 'N/A'}\n"
+        f"\n*(source: CoinGecko)*\n"
+    )
+    return md, meta

cyberagent/adapters/stock.py

@@ -0,0 +1,130 @@
+"""Stock data adapter — yfinance (no key; needs network).
+
+Covers US / HK / A-share via yfinance symbol mapping. Degrades gracefully to
+("", {"company_name": code}) when yfinance is missing or offline.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+from ..models import AssetInfo
+
+
+def _yf_symbol(asset_info: AssetInfo) -> str:
+    code = asset_info.code
+    if asset_info.type == "stock_cn":
+        # 600519.SH -> 600519.SS (Shanghai); .SZ / .BJ kept as yfinance expects
+        return code.replace(".SH", ".SS")
+    return code  # stock_us as-is; stock_hk already like 0700.HK
+
+
+async def fetch(asset_info: AssetInfo, *, timeout: float = 10.0) -> Tuple[str, dict]:
+    import asyncio
+    from datetime import datetime, timezone
+
+    code = asset_info.code
+    meta = {"company_name": code}
+
+    try:
+        import yfinance as yf
+    except ImportError:
+        return "", meta
+
+    sym = _yf_symbol(asset_info)
+
+    def _pull():
+        try:
+            t = yf.Ticker(sym)
+            info = t.info or {}
+            try:
+                hist = t.history(period="6mo", interval="1d")
+            except Exception:
+                hist = None
+            return info, hist
+        except Exception:
+            return {}, None
+
+    try:
+        info, hist = await asyncio.wait_for(asyncio.to_thread(_pull), timeout=timeout)
+    except Exception:
+        return "", meta
+    if not info:
+        return "", meta
+
+    name = info.get("longName") or info.get("shortName") or code
+    meta["company_name"] = name
+    price = info.get("currentPrice") or info.get("regularMarketPrice")
+    currency = info.get("currency", "")
+
+    fetched_at = datetime.now().astimezone().strftime("%Y-%m-%d %H:%M %Z")
+    mkt_epoch = info.get("regularMarketTime")
+    if isinstance(mkt_epoch, (int, float)):
+        quote_as_of = datetime.fromtimestamp(mkt_epoch, tz=timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    else:
+        quote_as_of = fetched_at
+    meta["fetched_at"] = fetched_at
+    meta["price"] = price
+
+    # ── price action: recent returns + parabolic/spike flag (so the chain can
+    #    SEE a narrative-driven run-up instead of treating a snapshot as stable) ──
+    hi52 = info.get("fiftyTwoWeekHigh")
+    lo52 = info.get("fiftyTwoWeekLow")
+    pa_lines, flags = [], []
+    try:
+        if hist is not None and len(hist) > 3:
+            close = hist["Close"].dropna()
+            last = float(close.iloc[-1])
+            for label, n in (("5D", 5), ("1M", 22), ("3M", 66)):
+                if len(close) > n:
+                    chg = (last / float(close.iloc[-n - 1]) - 1) * 100
+                    pa_lines.append(f"  - {label} change: {chg:+.1f}%")
+                    if label == "1M" and chg >= 40:
+                        flags.append(f"1-month move {chg:+.0f}% (steep run-up)")
+                    if label == "5D" and chg >= 25:
+                        flags.append(f"5-day move {chg:+.0f}% (vertical spike)")
+        if hi52 and price and float(price) / float(hi52) >= 0.95:
+            flags.append("price within 5% of 52-week high")
+        if hi52 and lo52 and float(lo52) > 0 and float(hi52) / float(lo52) >= 3:
+            flags.append(f"52-week range is {float(hi52)/float(lo52):.1f}x (very wide)")
+    except Exception:
+        pass
+    pa_block = ""
+    if pa_lines or flags:
+        pa_block = "\n#### Price action (CHECK BEFORE THESIS)\n" + "\n".join(pa_lines) + "\n"
+        if flags:
+            pa_block += ("- ⚠ **PARABOLIC / NARRATIVE-MOVE FLAG**: " + "; ".join(flags) +
+                         ". You MUST search WHY the price moved (catalyst / who said what / news) "
+                         "and treat a headline-driven spike as an AVOID/observe form, not a buy form.\n")
+    meta["price_flags"] = flags
+
+    md = (
+        f"### Company: {name} ({code})\n"
+        f"- **Data fetched at: {fetched_at}**  (cite this date; do not use a remembered/older price)\n"
+        f"- Sector / Industry: {info.get('sector', 'N/A')} / {info.get('industry', 'N/A')}\n"
+        f"- Country: {info.get('country', 'N/A')}\n"
+        f"- **Price ({currency}, as of {quote_as_of}): {price}**\n"
+        f"- Market cap: {info.get('marketCap')}\n"
+        f"- 52W high / low: {hi52} / {lo52}\n"
+        f"{pa_block}"
+        f"\n#### Valuation (note: market usually prices FORWARD)\n"
+        f"- P/E (trailing / **forward**): {info.get('trailingPE')} / {info.get('forwardPE')}\n"
+        f"- P/B: {info.get('priceToBook')} | P/S (trailing): {info.get('priceToSalesTrailing12Months')}\n"
+        f"- EV/EBITDA: {info.get('enterpriseToEbitda')} | PEG: {info.get('pegRatio')}\n"
+        f"\n#### Analyst consensus & ownership (cross-check 'is it already priced')\n"
+        f"- Mean target / high / low: {info.get('targetMeanPrice')} / {info.get('targetHighPrice')} / {info.get('targetLowPrice')}"
+        f"  (vs price {price}{' — ⚠ MEAN TARGET BELOW PRICE = overshoot signal' if (info.get('targetMeanPrice') and price and info.get('targetMeanPrice') < price) else ''})\n"
+        f"- # analysts: {info.get('numberOfAnalystOpinions')} | recommendation: {info.get('recommendationKey')} (mean {info.get('recommendationMean')})\n"
+        f"- Insider held %: {info.get('heldPercentInsiders')} | Institution held %: {info.get('heldPercentInstitutions')}\n"
+        f"\n#### Fundamentals\n"
+        f"- Total revenue: {info.get('totalRevenue')}\n"
+        f"- Revenue growth: {info.get('revenueGrowth')}\n"
+        f"- Earnings growth: {info.get('earningsGrowth')}\n"
+        f"- Gross margin: {info.get('grossMargins')} | Operating margin: {info.get('operatingMargins')} | Profit margin: {info.get('profitMargins')}\n"
+        f"- ROE: {info.get('returnOnEquity')} | ROA: {info.get('returnOnAssets')}\n"
+        f"- Free cash flow: {info.get('freeCashflow')} | Operating cash flow: {info.get('operatingCashflow')}\n"
+        f"- Total debt: {info.get('totalDebt')} | Debt/Equity: {info.get('debtToEquity')} | Current ratio: {info.get('currentRatio')}\n"
+        f"\n#### Business\n{(info.get('longBusinessSummary') or 'N/A')[:600]}\n"
+        f"\n*(source: yfinance, symbol {sym})*\n"
+    )
+    return md, meta

cyberagent/chain.py

@@ -0,0 +1,143 @@
+"""AnalystChain — the public entry point.
+
+    chain = AnalystChain(llm="gemini", api_key="...", lang="zh")
+    report = await chain.analyze("NVDA")
+
+Outer shape: classify -> fetch data -> run the 5 departments in sequence (each
+reads the upstream reports) -> parse the strategy dept's final decision ->
+AnalystReport. The analytical soul is the physical-bottleneck 5-step chain
+encoded in ``cyberagent.prompts``.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Optional, Sequence, Union
+
+from . import adapters
+from .classifier import classify
+from .depts import run_department, run_positioning
+from .llm_adapter import LLMAdapter, resolve_llm
+from .models import AnalystReport, FinalDecision
+from .prompts import DEPT_ORDER, get_department
+
+_DECISIONS = ("ACCUMULATE", "HOLD", "REDUCE", "AVOID")
+
+
+def _parse_verdict(markdown: str) -> tuple[Optional[FinalDecision], float, Optional[str]]:
+    """Best-effort extraction of final_decision / confidence / headline from the
+    closing (leaders) department's markdown."""
+    decision: Optional[FinalDecision] = None
+    up = markdown.upper()
+    # Prefer a decision near a "final decision" marker, else first occurrence.
+    marker = re.search(r"(FINAL DECISION|最终决策)(.{0,80})", up, re.DOTALL)
+    search_space = marker.group(2) if marker else up
+    for d in _DECISIONS:
+        if d in search_space:
+            decision = d  # type: ignore[assignment]
+            break
+    if decision is None:
+        for d in _DECISIONS:
+            if d in up:
+                decision = d  # type: ignore[assignment]
+                break
+
+    confidence = 0.0
+    # Skip an optional "(0-100)" scale label after the keyword, then grab the real number.
+    cm = re.search(
+        r"(?:置信度|confidence)\s*(?:[（(][^）)]*[）)])?\s*[:：]?\s*\n?\s*(\d{1,3})",
+        markdown, re.IGNORECASE,
+    )
+    if cm:
+        try:
+            confidence = min(100, int(cm.group(1))) / 100.0
+        except ValueError:
+            pass
+
+    headline = None
+    hm = re.search(r"(?:headline|反共识)[^\n]*\n+([^\n]{4,160})", markdown, re.IGNORECASE)
+    if hm:
+        headline = hm.group(1).strip().lstrip("#-* ").strip()
+
+    return decision, confidence, headline
+
+
+class AnalystChain:
+    def __init__(
+        self,
+        llm: Union[str, LLMAdapter] = "gemini",
+        *,
+        api_key: Optional[str] = None,
+        model: Optional[str] = None,
+        lang: str = "en",
+        departments: Optional[Sequence[str]] = None,
+        timeout: float = 10.0,
+    ):
+        self.llm = resolve_llm(llm, api_key=api_key, model=model)
+        self.lang = lang
+        self.departments = list(departments) if departments else list(DEPT_ORDER)
+        self.timeout = timeout
+
+    async def analyze(
+        self,
+        symbol: str,
+        *,
+        lang: Optional[str] = None,
+        departments: Optional[Sequence[str]] = None,
+        on_event=None,
+    ) -> AnalystReport:
+        """on_event(stage_key, label, status) — optional progress callback
+        (status in {'start','done'}); used by the CLI for live progress."""
+        lang = lang or self.lang
+        dept_keys = [k for k in DEPT_ORDER if k in (departments or self.departments)]
+        t0 = time.perf_counter()
+
+        def _emit(stage, label, status):
+            if on_event:
+                try:
+                    on_event(stage, label, status)
+                except Exception:
+                    pass
+
+        asset = classify(symbol)
+        report = AnalystReport(asset=asset, company_name=asset.code, market=asset.market)
+
+        if asset.type == "unknown":
+            report.success = False
+            report.error = f"Could not classify {symbol!r}. Try cn:/us:/hk:/crypto:/evm: prefix."
+            report.elapsed_seconds = round(time.perf_counter() - t0, 3)
+            return report
+
+        data_md, meta = await adapters.fetch(asset, timeout=self.timeout)
+        report.company_name = meta.get("company_name") or asset.code
+
+        # Phase 0: core business + physical-world positioning (grounds the whole chain)
+        _emit("positioning", "资产定位 / Positioning", "start")
+        report.positioning = await run_positioning(
+            llm=self.llm, company_name=report.company_name, code=asset.code,
+            market=asset.market, data_md=data_md, lang=lang,
+        )
+        _emit("positioning", "资产定位 / Positioning", "done")
+        pos_label = "资产定位 / Positioning"
+        grounded_md = f"## {pos_label}\n{report.positioning}\n\n## 原始数据 / Raw data\n{data_md}".strip()
+
+        prior: dict[str, str] = {}
+        for key in dept_keys:
+            spec = get_department(key)
+            label = spec["display_zh"] if lang == "zh" else spec["display_en"]
+            _emit(key, label, "start")
+            dr = await run_department(
+                key, llm=self.llm, company_name=report.company_name, code=asset.code,
+                market=asset.market, data_md=grounded_md, prior_reports=prior, lang=lang,
+            )
+            report.departments[key] = dr
+            prior[key] = dr.markdown
+            _emit(key, label, "done")
+
+        closer = report.departments.get("leaders")
+        if closer and closer.success:
+            report.final_decision, report.confidence, report.headline = _parse_verdict(closer.markdown)
+
+        report.elapsed_seconds = round(time.perf_counter() - t0, 3)
+        return report

cyberagent/classifier.py

@@ -0,0 +1,202 @@
+"""AssetClassifier — identify whether an input is a stock / token / contract
+and route it to the right data adapter.
+
+    classify("NVDA")        -> stock_us   code=NVDA
+    classify("600519")      -> stock_cn   code=600519.SH
+    classify("0700")        -> stock_hk   code=0700.HK
+    classify("BTC")         -> token      code=btc   coingecko_id=bitcoin
+    classify("0x6B17...")   -> evm_contract  chain=ethereum
+    classify("crypto:JUP")  -> token      code=jup   coingecko_id=jupiter-exchange-solana
+
+Explicit prefixes force routing: cn: / us: / hk: / crypto: / evm: / sol:
+"""
+
+from __future__ import annotations
+
+import re
+
+from .models import AssetInfo
+
+# ──────────────────────────────────────────────────────────────────────────
+# Token whitelist (symbol -> coingecko_id). Unknown symbols fall back to the
+# CoinGecko search API at fetch time.
+# ──────────────────────────────────────────────────────────────────────────
+TOKEN_WHITELIST: dict[str, str] = {
+    # Top market cap
+    "BTC": "bitcoin", "ETH": "ethereum", "USDT": "tether", "BNB": "binancecoin",
+    "SOL": "solana", "USDC": "usd-coin", "XRP": "ripple", "DOGE": "dogecoin",
+    "ADA": "cardano", "TRX": "tron", "AVAX": "avalanche-2", "TON": "the-open-network",
+    "DOT": "polkadot", "MATIC": "matic-network", "LINK": "chainlink",
+    "WBTC": "wrapped-bitcoin", "LTC": "litecoin", "BCH": "bitcoin-cash",
+    "NEAR": "near", "UNI": "uniswap", "XLM": "stellar", "ETC": "ethereum-classic",
+    "ATOM": "cosmos", "XMR": "monero", "FIL": "filecoin", "APT": "aptos",
+    "ARB": "arbitrum", "VET": "vechain", "OP": "optimism", "HBAR": "hedera-hashgraph",
+    "IMX": "immutable-x", "INJ": "injective-protocol", "SUI": "sui",
+    "RNDR": "render-token", "RENDER": "render-token", "GRT": "the-graph", "STX": "blockstack",
+    # DeFi blue chips
+    "AAVE": "aave", "MKR": "maker", "CRV": "curve-dao-token", "LDO": "lido-dao",
+    "COMP": "compound-governance-token", "SNX": "havven", "FXS": "frax-share",
+    "PENDLE": "pendle", "BAL": "balancer", "1INCH": "1inch", "RPL": "rocket-pool",
+    # L2 / Modular / Restaking
+    "TIA": "celestia", "EIGEN": "eigenlayer", "STRK": "starknet", "METIS": "metis-token",
+    "MNT": "mantle", "ZK": "zksync", "MANTA": "manta-network", "BLAST": "blast",
+    # Solana ecosystem
+    "JUP": "jupiter-exchange-solana", "JTO": "jito-governance-token", "PYTH": "pyth-network",
+    "WIF": "dogwifcoin", "BONK": "bonk", "POPCAT": "popcat", "W": "wormhole",
+    # AI / DePIN narratives
+    "TAO": "bittensor", "FET": "fetch-ai", "AGIX": "singularitynet", "OCEAN": "ocean-protocol",
+    "AKT": "akash-network", "NMR": "numeraire", "WLD": "worldcoin-wld",
+    # Meme
+    "PEPE": "pepe", "SHIB": "shiba-inu", "FLOKI": "floki", "BOME": "book-of-meme",
+    # RWA / stablecoin
+    "ONDO": "ondo-finance", "FRAX": "frax", "DAI": "dai", "TUSD": "true-usd",
+    # Others
+    "HYPE": "hyperliquid", "KAS": "kaspa", "GMX": "gmx", "DYDX": "dydx-chain",
+    "CFX": "conflux-token",
+}
+
+_SYMBOL_LOOKUP = {sym.lower(): cgid for sym, cgid in TOKEN_WHITELIST.items()}
+
+RE_EVM_CONTRACT = re.compile(r"^0x[a-fA-F0-9]{40}$")
+RE_CN_STOCK = re.compile(r"^(\d{6})(?:\.(SH|SZ|BJ))?$", re.IGNORECASE)
+RE_HK_STOCK = re.compile(r"^(\d{1,5})(?:\.HK)?$", re.IGNORECASE)
+RE_US_STOCK = re.compile(r"^[A-Z]{1,5}(\.[A-Z])?$")
+RE_SOL_ADDR = re.compile(r"^[1-9A-HJ-NP-Za-km-z]{32,44}$")
+
+
+def classify(raw: str, default_evm_chain: str = "ethereum") -> AssetInfo:
+    """Identify the asset type of a raw input. Always returns an AssetInfo
+    (type='unknown' rather than raising)."""
+    if not raw:
+        return AssetInfo(type="unknown", code="", raw_input="", confidence=0.0)
+
+    s = raw.strip()
+
+    # 0. Explicit prefix
+    if ":" in s:
+        prefix, _, rest = s.partition(":")
+        prefix = prefix.strip().lower()
+        rest = rest.strip()
+        if prefix == "cn":
+            return _cn_stock(rest, raw, forced=True)
+        if prefix == "us":
+            return _us_stock(rest, raw, forced=True)
+        if prefix == "hk":
+            return _hk_stock(rest, raw, forced=True)
+        if prefix in ("crypto", "token"):
+            return _token(rest, raw, forced=True)
+        if prefix == "evm":
+            return _evm_contract(rest, raw, default_evm_chain, forced=True)
+        if prefix in ("sol", "solana"):
+            return _solana(rest, raw, forced=True)
+
+    # 1. EVM contract (strictest)
+    if RE_EVM_CONTRACT.match(s):
+        return _evm_contract(s, raw, default_evm_chain, forced=False)
+
+    # 2. A-share (exactly 6 digits)
+    if RE_CN_STOCK.match(s):
+        return _cn_stock(s, raw, forced=False)
+
+    # 3. Token whitelist (before US stock so BTC/ETH/SOL resolve to token)
+    if s.lower() in _SYMBOL_LOOKUP:
+        return _token(s, raw, forced=False)
+
+    # 4. US stock (1-5 letters)
+    if RE_US_STOCK.match(s.upper()):
+        return _us_stock(s.upper(), raw, forced=False)
+
+    # 5. HK stock (1-5 digits, not 6)
+    if RE_HK_STOCK.match(s):
+        return _hk_stock(s, raw, forced=False)
+
+    # 6. Solana address (base58)
+    if RE_SOL_ADDR.match(s) and len(s) >= 32:
+        return _solana(s, raw, forced=False)
+
+    return AssetInfo(
+        type="unknown", code=s, raw_input=raw, confidence=0.0,
+        hints={"reason": "no matching pattern; try cn:/us:/hk:/crypto:/evm: prefix"},
+    )
+
+
+def _cn_stock(s: str, raw: str, forced: bool) -> AssetInfo:
+    s = s.strip().upper()
+    m = RE_CN_STOCK.match(s)
+    if not m:
+        digits = "".join(c for c in s if c.isdigit())
+        if len(digits) == 6:
+            s = digits
+            m = RE_CN_STOCK.match(s)
+    if m:
+        code_6, suffix = m.group(1), m.group(2)
+        if not suffix:
+            first = code_6[0]
+            suffix = "SH" if first in ("6", "9") else ("BJ" if first in ("8", "4") else "SZ")
+        return AssetInfo(
+            type="stock_cn", code=f"{code_6}.{suffix.upper()}", raw_input=raw,
+            market="CN", confidence=1.0 if not forced else 0.95,
+            hints={"exchange": suffix.upper()},
+        )
+    return AssetInfo(type="unknown", code=s, raw_input=raw, confidence=0.0,
+                     hints={"reason": "forced cn: but not 6-digit A-share format"})
+
+
+def _hk_stock(s: str, raw: str, forced: bool) -> AssetInfo:
+    digits = "".join(c for c in s.upper().replace(".HK", "") if c.isdigit())
+    if not digits or len(digits) > 5:
+        return AssetInfo(type="unknown", code=s, raw_input=raw, confidence=0.0,
+                         hints={"reason": "not a 1-5 digit HK code"})
+    code = f"{int(digits):04d}.HK"          # zero-pad to 4, e.g. 700 -> 0700.HK
+    return AssetInfo(type="stock_hk", code=code, raw_input=raw, market="HK",
+                     confidence=0.9 if forced else 0.7,
+                     hints={"note": "HK stock (numeric code)"})
+
+
+def _us_stock(s: str, raw: str, forced: bool) -> AssetInfo:
+    return AssetInfo(type="stock_us", code=s.strip().upper(), raw_input=raw, market="US",
+                     confidence=0.85 if not forced else 0.95,
+                     hints={"note": "US stock or unknown small-cap ticker"})
+
+
+def _token(s: str, raw: str, forced: bool) -> AssetInfo:
+    sym = s.strip().lower()
+    cgid = _SYMBOL_LOOKUP.get(sym)
+    if cgid:
+        return AssetInfo(type="token", code=sym, raw_input=raw, market="CRYPTO",
+                         coingecko_id=cgid, confidence=1.0, hints={"source": "whitelist"})
+    return AssetInfo(type="token", code=sym, raw_input=raw, market="CRYPTO",
+                     coingecko_id=None, confidence=0.5 if forced else 0.3,
+                     hints={"source": "unknown_symbol",
+                            "note": "not in whitelist; will search CoinGecko at fetch time"})
+
+
+def _evm_contract(s: str, raw: str, default_chain: str, forced: bool) -> AssetInfo:
+    addr = s.strip()
+    if not addr.startswith("0x"):
+        addr = "0x" + addr
+    addr = addr.lower()
+    if not RE_EVM_CONTRACT.match(addr):
+        return AssetInfo(type="unknown", code=addr, raw_input=raw, confidence=0.0,
+                         hints={"reason": "not a valid EVM address"})
+    return AssetInfo(type="evm_contract", code=addr, raw_input=raw, market="CRYPTO",
+                     chain=default_chain, confidence=1.0,
+                     hints={"note": "EVM address; chain defaulted"})
+
+
+def _solana(s: str, raw: str, forced: bool) -> AssetInfo:
+    addr = s.strip()
+    if not RE_SOL_ADDR.match(addr):
+        return AssetInfo(type="unknown", code=addr, raw_input=raw, confidence=0.0,
+                         hints={"reason": "not a valid Solana base58 address"})
+    return AssetInfo(type="solana_contract", code=addr, raw_input=raw, market="CRYPTO",
+                     chain="solana", confidence=0.95 if forced else 0.85,
+                     hints={"note": "Solana base58 address"})
+
+
+class AssetClassifier:
+    """Thin OO wrapper so `from cyberagent import AssetClassifier` works."""
+
+    @staticmethod
+    def classify(raw: str, default_evm_chain: str = "ethereum") -> AssetInfo:
+        return classify(raw, default_evm_chain=default_evm_chain)