Connectors

Ten source connectors ship with Hermes, each exposing an async fetch() that returns canonical records and sits behind the shared RawCache.

Source coverage spans global macro, financial markets, corporate filings, sanctions and governance intelligence. TTLs are deliberately conservative for stable public sources and tighter for fast-moving market data.

A connector answers one question: how do I get this source's data? In Hermes, each connector package pairs its fetch() with a parser, a normalizer and field mappings. Connectors can provide authentication, requests, pagination, rate limiting, retries and source-specific parsing — but generic retry, caching and validation belong to Hermes infrastructure, not to the connector.

Connectors use aiohttp with exponential-backoff retries (sleeps 2**attempt seconds) and resolve keys through RawCache.get_or_fetch.

from hermes import Hermes
hermes = Hermes(opensanction_api="x", new_data_api="x",
                sec_username="x", sec_email="x")

df = hermes.world_bank.fetch(
    country_code="BR",
    indicator_code="SP.POP.TOTL",   # total population
    frequency="Y",
)

# IMF WEO government debt (% of GDP)
df = hermes.imf.fetch(
    country="US",
    agency="IMF.RES",
    dataflow_id="WEO",
    key="GGXWDG_NGDP",
)

23 curated macro series are defined in fred/mappings.py, including GDPC1, A191RL1Q225SBEA, INDPRO, CPIAUCSL, CPILFESL, PCEPI, UNRATE, PAYEMS, CIVPART, FEDFUNDS, DGS10, DGS2, DGS3MO, T10Y2Y, T10Y3M, M2SL, TOTBKCR, HOUST, EXHOSLUSM495S, SP500, VIXCLS, DTWEXBGS.

fd = hermes.fred.fetch(series_id="CPIAUCSL")  # CPI

Endpoints (per binance/mappings.py): ohlcv, trades, aggregated_trades, order_book, best_bid_ask, 24hr, exchangeInfo; plus future-only fundingRate, openInterest, premiumIndex, openInterestHist, longShortRatio, topLongShortAccountRatio, topLongShortPositionRatio. fetch_history splits the range into 1000-bar windows fetched concurrently (semaphore = 10).

# 2 years of daily BTCUSDT futures candles
df = hermes.binance.fetch_history(
    symbol="BTCUSDT", interval="1d",
    market="future", years=2,
)

Endpoints: candles, quote, profile, metric, peers, earnings, insider, eps, ebitda, revenue, news, symbol. Lookback is capped by FINNHUB_MAX_DAYS per resolution (e.g. 1m/5m → 7d, 15m–1h → 30d, D/W/M → 365d).

Raised restricted intervals (raises ValueError for unsupported ones). The interval map: 1m/5m/15m/30m/1h/1d map to themselves, 1w → 1wk, 1M → 1mo.

Resolves a ticker to its CIK via sec-cik-mapper and requests <user-agent> <email> as required by the SEC. The SEC_TAG_MAP (sec/tags.py) maps canonical fields to XBRL GAAP tags — e.g. revenue, net_income, operating_cash_flow, long_term_debt, shares_outstanding, dividends, buybacks, etc.

Supports datasets such as us_ofac_sdn, eu_fsf, uk_fcdos and un_sc. Country ISO3 is converted to ISO2 internally before filtering.

The GDELT connector is scaffolded but not yet implemented — global news/event data powers the geopolitical features, which are similarly stubbed.

Reads bundled local CSVs, country-filtered with years converted to datetime:

Backoff sleeps 2**attempt seconds so transient failures settle quickly without hammering the source. Because retry, caching and validation are handled by Hermes infrastructure rather than each connector, adding a new source never means re-implementing that plumbing.