ticker-classifier 0.1.0__py3-none-any.whl

ticker_classifier/__init__.py

@@ -0,0 +1,4 @@
+from .classifier import TickerClassifier
+
+__all__ = ["TickerClassifier"]
+__version__ = "0.1.0"

ticker_classifier/apis/coingecko.py

@@ -0,0 +1,217 @@
+from collections import defaultdict
+from typing import Dict, List
+
+import aiohttp
+import requests
+
+
+class CoinGeckoClient:
+    def __init__(self):
+        """Initialize CoinGecko client.
+
+        Sets up base endpoints used for retrieving the coin list and simple
+        price information and initializes an internal cache for symbol -> id
+        mappings.
+
+        Notes
+        -----
+        The client keeps an in-memory `_crypto_map` that maps uppercase
+        symbols to a list of CoinGecko ids. This map is populated lazily by
+        `_load_map_sync` or `_load_map_async` when price lookup is requested.
+        """
+        self.list_url = "https://api.coingecko.com/api/v3/coins/list"
+        self.price_url = "https://api.coingecko.com/api/v3/simple/price"
+        self._crypto_map = None  # { 'BTC': ['bitcoin', 'bitcoin-token'], ... }
+
+    def _load_map_sync(self):
+        """Load the CoinGecko symbol->id map synchronously.
+
+        This method fetches the full coin list from the CoinGecko API and
+        populates the in-memory `_crypto_map` mapping uppercase symbol strings
+        to lists of CoinGecko ids. If the map is already loaded this is a
+        no-op.
+
+        Errors
+        ------
+        Any exceptions raised while fetching/parsing are caught and the map
+        falls back to an empty dict.
+        """
+        if self._crypto_map:
+            return
+        try:
+            resp = requests.get(self.list_url, timeout=10)
+            data = resp.json()
+            self._crypto_map = defaultdict(list)
+            for coin in data:
+                self._crypto_map[coin["symbol"].upper()].append(coin["id"])
+        except Exception:
+            self._crypto_map = {}
+
+    async def _load_map_async(self, session: aiohttp.ClientSession):
+        """Asynchronously load the CoinGecko symbol->id map.
+
+        Parameters
+        ----------
+        session : aiohttp.ClientSession
+            Active aiohttp session used for making the HTTP request.
+
+        Notes
+        -----
+        This is the async counterpart to `_load_map_sync`. If the internal map
+        is already populated this method returns immediately. Exceptions are
+        caught and the map will be set to an empty dict on failure.
+        """
+        if self._crypto_map:
+            return
+        try:
+            async with session.get(self.list_url) as resp:
+                data = await resp.json()
+                self._crypto_map = defaultdict(list)
+                for coin in data:
+                    self._crypto_map[coin["symbol"].upper()].append(coin["id"])
+        except Exception:
+            self._crypto_map = {}
+
+    def _get_candidate_ids(
+        self, symbols: List[str]
+    ) -> tuple[List[str], Dict[str, str]]:
+        """Return candidate CoinGecko ids for a list of symbols.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            Uppercase ticker symbols to map to CoinGecko ids.
+
+        Returns
+        -------
+        ids : list[str]
+            Flat list of candidate CoinGecko ids (limited to first 10
+            collisions per symbol).
+        id_to_parent : dict
+            Mapping of coin id -> original symbol (parent) used to group
+            results later.
+        """
+        ids = []
+        id_to_parent = {}
+        if not self._crypto_map:
+            return ids, id_to_parent
+
+        for sym in symbols:
+            if sym in self._crypto_map:
+                # Top 10 collisions only
+                for cid in self._crypto_map[sym][:10]:
+                    ids.append(cid)
+                    id_to_parent[cid] = sym
+        return ids, id_to_parent
+
+    def get_prices_sync(self, symbols: List[str]) -> Dict[str, Dict]:
+        """Synchronous price lookup for a list of symbols using CoinGecko.
+
+        This method ensures the internal symbol->id map is loaded, finds
+        candidate CoinGecko ids for the requested symbols, and retrieves USD
+        prices and market caps in chunks. The highest market cap candidate is
+        selected per symbol in `_process_response`.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            Uppercase ticker symbols to look up.
+
+        Returns
+        -------
+        dict[str, dict]
+            Mapping of symbol -> {"market_cap": ..., "name": ..., "id": ...}
+            for matches found. Returns an empty dict if nothing matched.
+        """
+        self._load_map_sync()
+        results = {}
+        ids, id_map = self._get_candidate_ids(symbols)
+        if not ids:
+            return results
+
+        chunk_size = 200
+        for i in range(0, len(ids), chunk_size):
+            chunk = ids[i : i + chunk_size]
+            try:
+                resp = requests.get(
+                    self.price_url,
+                    params={
+                        "ids": ",".join(chunk),
+                        "vs_currencies": "usd",
+                        "include_market_cap": "true",
+                    },
+                    timeout=10,
+                )
+                data = resp.json()
+                self._process_response(data, id_map, results)
+            except Exception:
+                pass
+        return results
+
+    async def get_prices_async(
+        self, session: aiohttp.ClientSession, symbols: List[str]
+    ) -> Dict[str, Dict]:
+        """Asynchronously retrieve prices and market caps for symbols.
+
+        Parameters
+        ----------
+        session : aiohttp.ClientSession
+            Active aiohttp session used to make HTTP requests.
+        symbols : list[str]
+            Uppercase ticker symbols to query.
+
+        Returns
+        -------
+        dict[str, dict]
+            Mapping of symbol -> {"market_cap": ..., "name": ..., "id": ...}.
+
+        Notes
+        -----
+        Uses the async map loader `_load_map_async` and requests CoinGecko in
+        chunks. Failures for a chunk are swallowed and processing continues.
+        """
+        await self._load_map_async(session)
+        results = {}
+        ids, id_map = self._get_candidate_ids(symbols)
+        if not ids:
+            return results
+
+        chunk_size = 200
+        for i in range(0, len(ids), chunk_size):
+            chunk = ids[i : i + chunk_size]
+            try:
+                params = {
+                    "ids": ",".join(chunk),
+                    "vs_currencies": "usd",
+                    "include_market_cap": "true",
+                }
+                async with session.get(self.price_url, params=params) as resp:
+                    data = await resp.json()
+                    self._process_response(data, id_map, results)
+            except Exception:
+                pass
+        return results
+
+    def _process_response(self, data, id_map, results):
+        """Process a CoinGecko price response and update results.
+
+        Parameters
+        ----------
+        data : dict
+            JSON-decoded response from the CoinGecko simple/price endpoint.
+        id_map : dict
+            Mapping of coin id -> parent symbol used to group results.
+        results : dict
+            Mutable mapping that will be updated in-place with the best
+            candidate per parent symbol (highest market cap wins).
+        """
+        for cid, val in data.items():
+            parent = id_map.get(cid)
+            if parent:
+                mcap = val.get("usd_market_cap", 0)
+                if mcap > results.get(parent, {}).get("market_cap", 0):
+                    results[parent] = {
+                        "market_cap": mcap,
+                        "name": cid.title(),
+                        "id": cid,
+                    }

ticker_classifier/apis/yahoo.py

@@ -0,0 +1,225 @@
+"""Yahoo Finance API helpers.
+
+This module provides a small client for obtaining the cookie/crumb
+credentials required by Yahoo Finance endpoints and for fetching quote
+data. Both synchronous (requests) and asynchronous (aiohttp) helpers
+are provided.
+
+Notes
+-----
+Docstrings follow the NumPy documentation style.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import aiohttp
+import requests
+
+API_BASE = "https://query2.finance.yahoo.com"
+COOKIE_URL = "https://fc.yahoo.com"
+CRUMB_URL = API_BASE + "/v1/test/getcrumb"
+QUOTE_URL = API_BASE + "/v7/finance/quote"
+
+HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
+}
+
+
+class YahooClient:
+    def __init__(self):
+        """Initialize a new :class:`YahooClient`.
+
+        The client maintains an in-memory cache of authentication
+        credentials (cookie + crumb) so repeated requests do not need to
+        re-authenticate on every call.
+
+        Returns
+        -------
+        None
+        """
+
+        self.credentials: Optional[Dict[str, Any]] = None
+
+    def _get_credentials_sync(self):
+        """Fetch cookie and crumb synchronously.
+
+        The method performs the two-step Yahoo flow synchronously:
+        1. Request the cookie from ``COOKIE_URL`` (allowing redirects).
+        2. Request the crumb token from ``CRUMB_URL`` using the
+           returned cookies.
+
+        Returns
+        -------
+        dict or None
+            Dictionary with keys ``'cookie'`` and ``'crumb'`` when
+            successful, otherwise ``None``.
+        """
+        if self.credentials:
+            return self.credentials
+
+        try:
+            # 1. Get Cookies (allow redirects)
+            # fc.yahoo.com redirects to a consent page or main page, setting cookies along the way
+            response_cookie = requests.get(COOKIE_URL, headers=HEADERS, timeout=5)
+            cookies = response_cookie.cookies
+
+            # 2. Get Crumb (using the cookies)
+            response_crumb = requests.get(
+                CRUMB_URL, headers=HEADERS, cookies=cookies, timeout=5
+            )
+            crumb = response_crumb.text
+
+            if crumb:
+                self.credentials = {"cookie": cookies, "crumb": crumb}
+        except Exception as e:
+            print(f"Yahoo Auth Error (Sync): {e}")
+
+        return self.credentials
+
+    def get_quotes_sync(self, symbols: List[str]) -> Dict[str, Dict]:
+        """Get quotes synchronously for the provided symbols.
+
+        Parameters
+        ----------
+        symbols : list of str
+            List of ticker symbols to query (e.g. ``['AAPL', 'MSFT']``).
+
+        Returns
+        -------
+        dict
+            Mapping from upper-case symbol to the quote data dictionary
+            returned by Yahoo. Returns an empty dict if no symbols are
+            provided or if a failure occurs.
+        """
+
+        results = {}
+        if not symbols:
+            return results
+
+        creds = self._get_credentials_sync()
+        if not creds:
+            print("Skipping Yahoo Sync: No credentials.")
+            return results
+
+        try:
+            params = {"symbols": ",".join(symbols), "crumb": creds["crumb"]}
+
+            resp = requests.get(
+                QUOTE_URL,
+                params=params,
+                cookies=creds["cookie"],
+                headers=HEADERS,
+                timeout=5,
+            )
+
+            if resp.status_code == 200:
+                data = resp.json()
+                if "quoteResponse" in data and "result" in data["quoteResponse"]:
+                    for item in data["quoteResponse"]["result"]:
+                        results[item["symbol"].upper()] = item
+            elif resp.status_code == 401:
+                # Credentials expired? Clear them for next time.
+                self.credentials = None
+                print("Yahoo 401 Unauthorized (Sync). Credentials cleared.")
+
+        except Exception as e:
+            print(f"Yahoo Sync Request Error: {e}")
+
+        return results
+
+    async def _get_credentials_async(self, session: aiohttp.ClientSession):
+        """Fetch cookie and crumb asynchronously.
+
+        Parameters
+        ----------
+        session : aiohttp.ClientSession
+            An aiohttp session used to make the requests. The session's
+            cookie jar will be used to collect cookies from Yahoo's
+            redirects.
+
+        Returns
+        -------
+        dict or None
+            Dictionary with keys ``'cookie'`` and ``'crumb'`` when
+            successful, otherwise ``None``.
+        """
+        if self.credentials:
+            return self.credentials
+
+        try:
+            # 1. Get Cookies
+            # aiohttp session handles cookies automatically in its cookie_jar if we share the session.
+            # However, to be safe and explicit (since we pass cookies manually later), we extract them.
+            async with session.get(COOKIE_URL, headers=HEADERS) as resp:
+                await resp.read()  # Read body to ensure cookies are processed
+                # Access cookies from the response history or the session cookie jar
+                pass
+
+            # 2. Get Crumb
+            # The session now holds the cookies from step 1
+            async with session.get(CRUMB_URL, headers=HEADERS) as resp:
+                crumb = await resp.text()
+
+                if crumb:
+                    # We grab the cookies directly from the session's cookie jar to save them
+                    # Dictionary comprehension to convert to standard dict
+                    cookies = {
+                        k: v.value
+                        for k, v in session.cookie_jar.filter_cookies(CRUMB_URL).items()
+                    }
+                    self.credentials = {"cookie": cookies, "crumb": crumb}
+
+        except Exception as e:
+            print(f"Yahoo Auth Error (Async): {e}")
+
+        return self.credentials
+
+    async def get_quotes_async(
+        self, session: aiohttp.ClientSession, symbols: List[str]
+    ) -> Dict[str, Dict]:
+        """Asynchronously get quotes for the provided symbols.
+
+        Parameters
+        ----------
+        session : aiohttp.ClientSession
+            Active aiohttp session used to perform the requests.
+        symbols : list of str
+            List of ticker symbols to query.
+
+        Returns
+        -------
+        dict
+            Mapping from upper-case symbol to the quote data dictionary
+            returned by Yahoo. Returns an empty dict if no symbols are
+            provided or if a failure occurs.
+        """
+
+        results = {}
+        if not symbols:
+            return results
+
+        creds = await self._get_credentials_async(session)
+        if not creds:
+            print("Skipping Yahoo Async: No credentials.")
+            return results
+
+        try:
+            params = {"symbols": ",".join(symbols), "crumb": creds["crumb"]}
+
+            # aiohttp allows passing cookies as a dict
+            async with session.get(
+                QUOTE_URL, params=params, cookies=creds["cookie"], headers=HEADERS
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    if "quoteResponse" in data and "result" in data["quoteResponse"]:
+                        for item in data["quoteResponse"]["result"]:
+                            results[item["symbol"].upper()] = item
+                elif resp.status == 401:
+                    self.credentials = None
+                    print("Yahoo 401 Unauthorized (Async). Credentials cleared.")
+
+        except Exception as e:
+            print(f"Yahoo Async Request Error: {e}")
+
+        return results

ticker_classifier/classifier.py

@@ -0,0 +1,240 @@
+import asyncio
+from typing import Dict, List
+
+import aiohttp
+
+from .apis.coingecko import CoinGeckoClient
+from .apis.yahoo import YahooClient
+from .constants import MAJOR_FOREX, MINOR_FOREX, SHORTCUTS
+from .db.cache import TickerCache
+
+
+class TickerClassifier:
+    def __init__(self, db_name: str = "ticker_cache.db", hours_to_expire: int = 24):
+        """Create a TickerClassifier instance.
+
+        Parameters
+        ----------
+        db_name : str, optional
+            SQLite filename for the `TickerCache`, by default "ticker_cache.db".
+        hours_to_expire : int, optional
+            Hours after which cached entries expire, by default 24.
+        """
+        self.cache = TickerCache(db_name, hours_to_expire)
+        self.yahoo = YahooClient()
+        self.cg = CoinGeckoClient()
+
+    def _process_duel(
+        self, to_process: List[str], yahoo_data: Dict, crypto_data: Dict
+    ) -> Dict:
+        """Resolve competing category signals for each symbol.
+
+        The classifier considers three possible sources for each symbol:
+        stock (Yahoo), crypto (CoinGecko), and forex (heuristics). Each source
+        receives a numeric score (market cap or heuristic weight) and the
+        highest-scoring source determines the final classification.
+
+        Parameters
+        ----------
+        to_process : list[str]
+            Uppercase symbols to evaluate.
+        yahoo_data : dict
+            Mapping of symbol -> Yahoo quote dict (as returned by `YahooClient`).
+        crypto_data : dict
+            Mapping of symbol -> CoinGecko-derived dict containing at least
+            a `market_cap` key.
+
+        Returns
+        -------
+        dict
+            Mapping of symbol -> final classification dict containing keys
+            such as `category`, `ticker`, `name`, `market_cap`, and
+            `yahoo_lookup`.
+        """
+        processed = {}
+        # Init structure
+        duel = {
+            s: {"stock": 0, "crypto": 0, "forex": 0, "details": {}} for s in to_process
+        }
+
+        # 1 MILLION USD THRESHOLD
+        # If a crypto is smaller than this, we treat it as "Noise" if it clashes with a stock ticker.
+        MIN_CRYPTO_MCAP = 1_000_000
+
+        for sym in to_process:
+            # 1. Forex Heuristics
+            if sym in MAJOR_FOREX:
+                duel[sym]["forex"] = 100_000_000_000_000
+                duel[sym]["details"]["forex"] = {
+                    "type": "Forex",
+                    "name": f"{sym} Currency",
+                    "market_cap": None,
+                }
+            elif sym in MINOR_FOREX:
+                duel[sym]["forex"] = 50_000_000
+                duel[sym]["details"]["forex"] = {
+                    "type": "Forex",
+                    "name": f"{sym} Currency",
+                    "market_cap": None,
+                }
+
+            # 2. Stock Data
+            if sym in yahoo_data:
+                info = yahoo_data[sym]
+                qtype = info.get("quoteType", "UNKNOWN")
+                raw_mcap = info.get("marketCap", 0)
+                score = raw_mcap
+
+                # Boost logic
+                if qtype == "INDEX":
+                    score = 50_000_000_000
+                if qtype == "FUTURE":
+                    score = 10_000_000_000
+
+                # If we found a valid stock object but mcap is missing/0,
+                # give it a base score so it beats tiny cryptos.
+                if score == 0 and qtype in ["EQUITY", "ETF"]:
+                    score = 250_000  # Assume at least micro-cap stock
+
+                duel[sym]["stock"] = score
+                duel[sym]["details"]["stock"] = {
+                    "type": qtype,
+                    "name": info.get("shortName") or info.get("longName"),
+                    "market_cap": raw_mcap,
+                }
+
+            # 3. Crypto Data
+            if sym in crypto_data:
+                info = crypto_data[sym]
+                mcap = info.get("market_cap", 0)
+                duel[sym]["crypto"] = mcap
+                duel[sym]["details"]["crypto"] = {
+                    "type": "Crypto",
+                    "name": info.get("name"),
+                    "market_cap": mcap,
+                }
+
+            # 4. Resolve
+            scores = duel[sym]
+            winner = max(["stock", "crypto", "forex"], key=lambda k: scores[k])
+
+            # If Crypto won, but it's tiny (< $1M), and we tried to look up a Stock...
+            # It's highly likely this is a "Fake" token or the Yahoo lookup failed.
+            if winner == "crypto":
+                mcap = scores["crypto"]
+                if mcap < MIN_CRYPTO_MCAP:
+                    # If the stock score was 0 (Yahoo failed), we'd rather return "Unknown"
+                    # than return a $1,000 junk token for "NVDA".
+                    winner = "unknown"
+
+            # Construct Result
+            if winner == "unknown" or scores[winner] == 0:
+                final = {"category": "Unknown", "ticker": sym}
+            else:
+                details = scores["details"].get(winner, {})
+                alternatives = [
+                    k
+                    for k in ["stock", "crypto", "forex"]
+                    if scores[k] > 0 and k != winner
+                ]
+
+                y_look = sym
+                if winner == "crypto":
+                    y_look = f"{sym}-USD"
+                elif winner == "forex":
+                    y_look = f"{sym}USD=X"
+
+                final = {
+                    "category": winner if winner != "stock" else details.get("type"),
+                    "ticker": sym,
+                    "name": details.get("name"),
+                    "market_cap": details.get("market_cap"),
+                    "yahoo_lookup": y_look,
+                    "alternatives": alternatives,
+                    "source": "api",
+                }
+            processed[sym] = final
+        return processed
+
+    def classify(self, symbols: List[str]) -> List[Dict]:
+        """Synchronously classify a list of ticker-like symbols.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            Iterable of symbols (may contain duplicates or mixed case). The
+            returned list preserves the order of the input list with each
+            element replaced by its classification dict or `None`.
+
+        Returns
+        -------
+        list[dict]
+            List of classification dictionaries aligned with the input order.
+        """
+        unique = list({s.upper().strip() for s in symbols if s.strip()})
+        results_map = {}
+        to_process = []
+
+        # Cache check
+        cached = self.cache.get_many(unique)
+        for sym in unique:
+            if sym in SHORTCUTS:
+                results_map[sym] = {**SHORTCUTS[sym], "source": "shortcut"}
+            elif sym in cached:
+                results_map[sym] = cached[sym]
+            else:
+                to_process.append(sym)
+
+        if to_process:
+            y_res = self.yahoo.get_quotes_sync(to_process)
+            c_res = self.cg.get_prices_sync(to_process)
+            processed = self._process_duel(to_process, y_res, c_res)
+            self.cache.save_many(processed)
+            results_map.update(processed)
+
+        return [results_map.get(s.upper().strip()) for s in symbols]
+
+    async def classify_async(self, symbols: List[str]) -> List[Dict]:
+        """Asynchronously classify a list of ticker-like symbols.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            List of symbols to classify. Input order is preserved in the
+            returned list.
+
+        Returns
+        -------
+        list[dict]
+            Classification results aligned with the input list; entries may
+            be `None` for unknown symbols.
+        """
+        unique = list({s.upper().strip() for s in symbols if s.strip()})
+        results_map = {}
+        to_process = []
+
+        # Cache Read (Run in thread to avoid blocking loop)
+        loop = asyncio.get_running_loop()
+        cached = await loop.run_in_executor(None, self.cache.get_many, unique)
+
+        for sym in unique:
+            if sym in SHORTCUTS:
+                results_map[sym] = {**SHORTCUTS[sym], "source": "shortcut"}
+            elif sym in cached:
+                results_map[sym] = cached[sym]
+            else:
+                to_process.append(sym)
+
+        if to_process:
+            async with aiohttp.ClientSession() as session:
+                task_y = self.yahoo.get_quotes_async(session, to_process)
+                task_c = self.cg.get_prices_async(session, to_process)
+                y_res, c_res = await asyncio.gather(task_y, task_c)
+
+            processed = self._process_duel(to_process, y_res, c_res)
+
+            # Cache Write (Run in thread)
+            await loop.run_in_executor(None, self.cache.save_many, processed)
+            results_map.update(processed)
+
+        return [results_map.get(s.upper().strip()) for s in symbols]

ticker_classifier/constants.py

@@ -0,0 +1,192 @@
+MAJOR_FOREX = {"USD", "EUR", "JPY", "GBP", "AUD", "CAD", "CHF", "CNY", "HKD", "NZD"}
+
+MINOR_FOREX = {
+    "AED",
+    "AFN",
+    "ALL",
+    "AMD",
+    "ANG",
+    "AOA",
+    "ARS",
+    "AWG",
+    "AZN",
+    "BAM",
+    "BBD",
+    "BDT",
+    "BGN",
+    "BHD",
+    "BIF",
+    "BMD",
+    "BND",
+    "BOB",
+    "BRL",
+    "BSD",
+    "BTN",
+    "BWP",
+    "BYN",
+    "BZD",
+    "CLP",
+    "COP",
+    "CRC",
+    "CUP",
+    "CVE",
+    "CZK",
+    "DJF",
+    "DKK",
+    "DOP",
+    "DZD",
+    "EGP",
+    "ERN",
+    "ETB",
+    "FJD",
+    "FKP",
+    "GEL",
+    "GHS",
+    "GIP",
+    "GMD",
+    "GNF",
+    "GTQ",
+    "GYD",
+    "HNL",
+    "HRK",
+    "HTG",
+    "HUF",
+    "IDR",
+    "ILS",
+    "INR",
+    "IQD",
+    "IRR",
+    "ISK",
+    "JMD",
+    "JOD",
+    "KES",
+    "KGS",
+    "KHR",
+    "KMF",
+    "KPW",
+    "KRW",
+    "KWD",
+    "KYD",
+    "KZT",
+    "LAK",
+    "LBP",
+    "LKR",
+    "LRD",
+    "LSL",
+    "LYD",
+    "MAD",
+    "MDL",
+    "MGA",
+    "MKD",
+    "MMK",
+    "MNT",
+    "MOP",
+    "MRU",
+    "MUR",
+    "MVR",
+    "MWK",
+    "MXN",
+    "MYR",
+    "MZN",
+    "NAD",
+    "NGN",
+    "NIO",
+    "NOK",
+    "NPR",
+    "OMR",
+    "PAB",
+    "PEN",
+    "PGK",
+    "PHP",
+    "PKR",
+    "PLN",
+    "PYG",
+    "QAR",
+    "RON",
+    "RSD",
+    "RUB",
+    "RWF",
+    "SAR",
+    "SBD",
+    "SCR",
+    "SDG",
+    "SEK",
+    "SGD",
+    "SHP",
+    "SLL",
+    "SOS",
+    "SRD",
+    "SSP",
+    "STN",
+    "SYP",
+    "SZL",
+    "THB",
+    "TJS",
+    "TMT",
+    "TND",
+    "TOP",
+    "TRY",
+    "TTD",
+    "TWD",
+    "TZS",
+    "UAH",
+    "UGX",
+    "UYU",
+    "UZS",
+    "VES",
+    "VND",
+    "VUV",
+    "WST",
+    "XAF",
+    "XCD",
+    "XOF",
+    "XPF",
+    "YER",
+    "ZAR",
+    "ZMW",
+}
+
+SHORTCUTS = {
+    "DXY": {
+        "category": "Index",
+        "ticker": "DXY",
+        "name": "US Dollar Index",
+        "yahoo_lookup": "DX-Y.NYB",
+    },
+    "VIX": {
+        "category": "Index",
+        "ticker": "VIX",
+        "name": "CBOE Volatility Index",
+        "yahoo_lookup": "^VIX",
+    },
+    "GOLD": {
+        "category": "Commodity",
+        "ticker": "GOLD",
+        "name": "Gold",
+        "yahoo_lookup": "GC=F",
+    },
+    "SILVER": {
+        "category": "Commodity",
+        "ticker": "SILVER",
+        "name": "Silver",
+        "yahoo_lookup": "SI=F",
+    },
+    "OIL": {
+        "category": "Commodity",
+        "ticker": "OIL",
+        "name": "Crude Oil",
+        "yahoo_lookup": "CL=F",
+    },
+    "SPX": {
+        "category": "Index",
+        "ticker": "SPX",
+        "name": "S&P 500",
+        "yahoo_lookup": "^GSPC",
+    },
+    "SPY": {
+        "category": "ETF",
+        "ticker": "SPY",
+        "name": "SPDR S&P 500 ETF Trust",
+        "yahoo_lookup": "SPY",
+    },
+}

ticker_classifier/db/cache.py

@@ -0,0 +1,93 @@
+import json
+import sqlite3
+from datetime import datetime, timedelta
+from typing import Any, Dict, List
+
+
+class TickerCache:
+    def __init__(self, db_name: str, hours_to_expire: int):
+        """Initialize the ticker cache.
+
+        Parameters
+        ----------
+        db_name : str
+            Path or name of the SQLite database file used for caching.
+        hours_to_expire : int
+            Number of hours after which cached entries are considered expired.
+        """
+        self.db_name = db_name
+        self.hours_to_expire = hours_to_expire
+        self._init_db()
+
+    def _init_db(self):
+        """Create the `tickers` table if it does not already exist.
+
+        The table stores `symbol` as the primary key, the JSON-serialized
+        `data` blob and an ISO-formatted `updated_at` timestamp.
+        """
+        with sqlite3.connect(self.db_name) as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS tickers (
+                    symbol TEXT PRIMARY KEY,
+                    data TEXT,
+                    updated_at TEXT 
+                )
+            """
+            )
+
+    def get_many(self, symbols: List[str]) -> Dict[str, Any]:
+        """Retrieve multiple cached ticker entries that are not expired.
+
+        Parameters
+        ----------
+        symbols : list[str]
+            List of symbol strings to fetch from cache. If empty, returns an
+            empty dict.
+
+        Returns
+        -------
+        dict[str, Any]
+            Mapping of symbol -> deserialized cache object. Each returned
+            object will have a `source` key set to `'cache'`.
+        """
+        if not symbols:
+            return {}
+        cutoff = (datetime.now() - timedelta(hours=self.hours_to_expire)).isoformat()
+        results = {}
+
+        with sqlite3.connect(self.db_name) as conn:
+            cursor = conn.cursor()
+            placeholders = ",".join("?" * len(symbols))
+            query = f"SELECT symbol, data FROM tickers WHERE symbol IN ({placeholders}) AND updated_at > ?"
+            cursor.execute(query, symbols + [cutoff])
+            for s, d in cursor.fetchall():
+                results[s] = json.loads(d)
+                results[s]["source"] = "cache"
+        return results
+
+    def save_many(self, items: Dict[str, Any]):
+        """Save multiple items to the cache.
+
+        Parameters
+        ----------
+        items : dict[str, Any]
+            Mapping of symbol -> item dict. Items with `category == 'Unknown'`
+            are not persisted. The optional `source` key is stripped before
+            saving.
+        """
+        if not items:
+            return
+        with sqlite3.connect(self.db_name) as conn:
+            cursor = conn.cursor()
+            now = datetime.now().isoformat()
+            data_tuples = []
+            for s, d in items.items():
+                if d.get("category") != "Unknown":
+                    clean = {k: v for k, v in d.items() if k != "source"}
+                    data_tuples.append((s, json.dumps(clean), now))
+            if data_tuples:
+                cursor.executemany(
+                    "INSERT OR REPLACE INTO tickers (symbol, data, updated_at) VALUES (?, ?, ?)",
+                    data_tuples,
+                )

ticker_classifier-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: ticker_classifier
+Version: 0.1.0
+Summary: A robust stock, crypto, and forex classifier with async support.
+Author-email: Stephan Akkerman <stephan@akkerman.ai>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: aiohttp
+Dynamic: license-file
+
+# ticker-classifier
+
+<!-- Add a banner here like: https://github.com/StephanAkkerman/fintwit-bot/blob/main/img/logo/fintwit-banner.png -->
+
+---
+<!-- Adjust the link of the first and second badges to your own repo -->
+<p align="center">
+  <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/StephanAkkerman/ticker-classifier/pyversions.yml?label=python%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13&logo=python&style=flat-square">
+  <img src="https://img.shields.io/github/license/StephanAkkerman/ticker-classifier.svg?color=brightgreen" alt="License">
+  <a href="https://github.com/psf/black"><img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black"></a>
+</p>
+
+## Introduction
+
+`ticker-classifier` is a small Python library for classifying ticker-like symbols (for example `AAPL`, `BTC`, `EUR`, `GOLD`) into a simple market/category representation.
+It uses Yahoo Finance for equities, CoinGecko for cryptocurrencies and a few heuristics for currencies/commodities. The output indicates the most likely category, a display name, market cap when available, and a `yahoo_lookup` value to fetch further data if desired.
+
+## Table of Contents 🗂
+
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API](#api)
+- [Development](#development)
+- [Release and Versioning](#release-and-versioning)
+- [Citation](#citation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Key Features 🔑
+
+- Classify symbols as `Equity`, `Crypto`, `Forex`, `Commodity`, `Index` or `Unknown`.
+- Uses multiple public APIs and simple heuristics to make robust decisions.
+- Provides both synchronous and asynchronous APIs.
+- Lightweight disk cache to avoid repeated lookups (`TickerCache`).
+
+## Installation ⚙️
+
+Install from pip using the provided `requirements.txt` or install the package directly from the repository for latest changes:
+
+```bash
+pip install -r requirements.txt
+```
+
+or
+
+```bash
+pip install git+https://github.com/StephanAkkerman/ticker-classifier.git
+```
+
+## Usage ⌨️
+
+Basic synchronous usage:
+
+```python
+from ticker_classifier.classifier import TickerClassifier
+
+classifier = TickerClassifier()
+symbols = ["AAPL", "BTC", "EUR", "GOLD", "UNKNOWN123"]
+results = classifier.classify(symbols)
+for r in results:
+    print(r)
+```
+
+Example asynchronous usage:
+
+```python
+import asyncio
+from ticker_classifier.classifier import TickerClassifier
+
+async def main():
+    classifier = TickerClassifier()
+    symbols = ["AAPL", "BTC", "ETH", "JPY"]
+    results = await classifier.classify_async(symbols)
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
+The output for each symbol is a dictionary like:
+
+```python
+{'category': 'EQUITY', 'ticker': 'AAPL', 'name': 'Apple Inc.', 'market_cap': 4029017227264, 'yahoo_lookup': 'AAPL', 'alternatives': ['crypto'], 'source': 'api'}
+{'category': 'crypto', 'ticker': 'BTC', 'name': 'Bitcoin', 'market_cap': 1736590593460.9607, 'yahoo_lookup': 'BTC-USD', 'alternatives': ['stock'], 'source': 'api'}
+{'category': 'crypto', 'ticker': 'ETH', 'name': 'Ethereum', 'market_cap': 338145915081.1455, 'yahoo_lookup': 'ETH-USD', 'alternatives': ['stock'], 'source': 'cache'}
+{'category': 'forex', 'ticker': 'JPY', 'name': 'JPY Currency', 'market_cap': None, 'yahoo_lookup': 'JPYUSD=X', 'alternatives': ['stock'], 'source': 'cache'}
+```
+
+Notes
+- The classifier caches positive classifications (non-`Unknown`) in an
+SQLite database (default `ticker_cache.db`) for `24` hours by default.
+- You can customize the cache filename and expiry by passing `db_name` and
+`hours_to_expire` to `TickerClassifier`.
+
+## API
+
+- `ticker_classifier.classifier.TickerClassifier`
+- `classify(symbols: List[str]) -> List[dict]` – synchronous classification.
+- `classify_async(symbols: List[str]) -> List[dict]` – async classification.
+- `ticker_classifier.apis.yahoo.YahooClient` – low-level Yahoo quote fetcher (sync + async helpers).
+- `ticker_classifier.apis.coingecko.CoinGeckoClient` – crypto lookup + market cap helpers (sync + async).
+- `ticker_classifier.db.cache.TickerCache` – tiny SQLite-backed cache used by `TickerClassifier`.
+
+## Development
+
+Run formatting and linting tools you prefer (project uses `black` code style).
+
+Run a quick smoke check by running the `classifier.py` module directly:
+
+```powershell
+& .venv\Scripts\python.exe ticker_classifier\classifier.py
+```
+
+If you add tests, run them with your chosen test runner (e.g. `pytest`).
+
+## Release and Versioning
+
+This package is published to PyPI through GitHub Actions:
+
+- Workflow: `.github/workflows/publish.yml`
+- Trigger: GitHub Release published
+- Publisher: `pypa/gh-action-pypi-publish` using trusted publishing (OIDC)
+
+Release flow:
+
+1. Update version in `pyproject.toml`.
+2. Update `ticker_classifier/__init__.py` `__version__` to match.
+3. Commit and push.
+4. Create a GitHub release with tag `vX.Y.Z` (or `X.Y.Z`).
+
+The publish workflow validates that the release tag version matches `pyproject.toml` before uploading to PyPI.
+
+## Citation ✍️
+If you use this project in your research, please cite as follows (adjust
+metadata accordingly):
+
+```bibtex
+@misc{ticker-classifier,
+author  = {Stephan Akkerman},
+title   = {ticker-classifier},
+year    = {2025},
+publisher = {GitHub},
+howpublished = {\url{https://github.com/StephanAkkerman/ticker-classifier}}
+}
+```
+
+## Contributing 🛠
+
+Contributions are welcome. Suggested workflow:
+
+1. Fork the repository and create a feature branch.
+2. Run tests and format your changes with `black`.
+3. Open a pull request with a clear description of the change.
+
+Please open issues for feature requests or bugs and include a small
+reproducible example when possible.
+
+![https://github.com/StephanAkkerman/ticker-classifier/graphs/contributors](https://contributors-img.firebaseapp.com/image?repo=StephanAkkerman/ticker-classifier)
+
+## License 📜
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

ticker_classifier-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+ticker_classifier/__init__.py,sha256=X35OW2LFeV0GXY-lkZKNVOpiIMHm2gEsXxs5txD17-A,95
+ticker_classifier/classifier.py,sha256=QrZK1QZCSDWtZFeFzUNhuC3o-Pmc8rMOoyrcpcs0BlQ,8918
+ticker_classifier/constants.py,sha256=MzTG-PeFm8EjtVjbPtBGKnyWaeR5Arh7rAkvRaUyyNU,2682
+ticker_classifier/apis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ticker_classifier/apis/coingecko.py,sha256=a7hwT52-hGc-u6TSLQ2li06qqkVpRecuWrcmcJdpy7I,7603
+ticker_classifier/apis/yahoo.py,sha256=4TmCfK9prMZ7VCc6ZoWqAgBCRTICOlK02ewNH-W7Xpo,7696
+ticker_classifier/db/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ticker_classifier/db/cache.py,sha256=oTd_aGJ-NU0Jyf1SnpuKeALKcNg3GW6W0RziwuzGMiM,3257
+ticker_classifier-0.1.0.dist-info/licenses/LICENSE,sha256=M4a6e_RgNGKdxALQ8kkRG280OdA6w5Y3RLHwneYEbq4,1073
+ticker_classifier-0.1.0.dist-info/METADATA,sha256=ZV9ecU1pLhO6UgK8nBwzWk848xXg8RVjsFahq7arMks,6358
+ticker_classifier-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ticker_classifier-0.1.0.dist-info/top_level.txt,sha256=aaVnIjqeRswEK3Ph2fWR_9GgI16UCON513u7YDX9mmQ,18
+ticker_classifier-0.1.0.dist-info/RECORD,,

ticker_classifier-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ticker_classifier-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Stephan Akkerman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ticker_classifier-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ticker_classifier