Reference

API Reference

The public surface of Hermes, centered on the Hermes facade, the RawCache, the scheduler, entities and constants.

Reference index

Section	What you'll find
Hermes facade	constructor, attributes, clear_cache, cache_stats
RawCache	get / put / get_or_fetch / clear / stats
Scheduler	schedule, start, stop, run_now, list_jobs & cron spec
Entities	countries, iso3_to_iso2, check_iso3, get_cik
Constants	SYMBOLS, TICKERS, CANONICAL_FREQS & more
Dataset	the pydantic BaseModel and its fields
Feature registry	LineageGraph and TieredPlan

Hermes facade

constructor

Hermes(
    opensanction_api: str,
    new_data_api: str,
    fred_api: str,
    sec_username: str,
    sec_email: str,
    finnhub_api: str,
    cache_dir: str | None = None,
    use_cache: bool = True,
) -> Hermes

Raises KeyError if both opensanction_api and new_data_api are empty. Creates a shared RawCache(cache_dir) unless use_cache=False.

Attribute	Type	Notes
list_countries	list[str]	249 ISO-3 codes
lf	features	feature registry facade
list_features	list[Callable]	= lf.list_features() (~57 features)
country_features	pipeline	country-risk pipeline
ta_feature	TAfeatures	technical analysis
fa_features	FAfeatures	fundamental analysis
crypto_history	CryptoHistory	crypto history
filling_history	CompanyFiling	company filing history
world_bank, imf, fred	connector	global macro
gdelt	GDELT	stub
opensanction	OpenSanction	sanctions
binance, finnhub, yfin	connector	markets
sec_edger	SECEDGAR	SEC filings (sic)
datasets	PUBLIC_DATASET	bundled CSVs

methods

def clear_cache(self, older_than: str | None = None) -> None
    # older_than: e.g. "7d", "24h", "2w" — parsed into timedelta

def cache_stats(self) -> dict
    # -> {"total_files", "by_source", "hits", "misses", "hit_rate"}

RawCache

In hermes/acquisition/cache.py. Default dir ~/.hermes_cache/raw, default TTL 24h. Cache keys are sha256(source + json_params)[:16], stored as <dir>/<source>/<hash>.parquet.

python

RawCache(cache_dir: str | Path | None = None)

get(source, params, ttl=None)                    # raises CacheMiss on miss/expiry/corruption
put(source, params, df)                          # writes parquet + .meta.json
get_or_fetch(source, params, fetch_fn,           # cache unless force, else await & cache
             force=False, ttl=None)
clear(older_than: timedelta | None = None)       # delete .parquet (+ meta)
stats() -> {"total_files", "by_source",
            "hits", "misses", "hit_rate"}

Scheduler

A full asyncio scheduler in hermes/core/scheduler.py supporting interval and cron specs.

python

from hermes.core.scheduler import schedule, start, stop, run_now, list_jobs

@schedule(time="daily", name="nightly_refresh", timeout=600.0, retries=3)
async def refresh(dataset):
    ...

start()                     # runs loop until KeyboardInterrupt
stop()
run_now("nightly_refresh")  # async: run_now_async; sync wrapper via asyncio.run
list_jobs()                 # name, schedule, next_run, last_run, last_status, runs, failures

Spec	Meaning
"hourly" / "daily" / "weekly"	1h / 1d / 1w aliases
"30m" / "2d" / "3w"	Numeric interval suffixes (m, h, d, w)
"0 3 * * *"	5-field cron: min hour day month weekday (Sun=0)

Cron supports *, ranges a-b, steps */n and a-b/n, and comma lists. Retries use exponential backoff capped at 60s.

Entities

python

from hermes.entities.countries import countries, iso3_to_iso2, check_iso3
from hermes.entities.companies import get_cik

countries          # list[str] of 249 ISO-3 codes
iso3_to_iso2("USA")   # -> "US"
check_iso3("USA")     # -> None; raises RuntimeError if not ISO3
get_cik("AAPL")       # -> "CIK0320193" or "Not Found"

Constants

Constant	Content
SYMBOLS	20 crypto symbols: BTCUSDT, ETHUSDT, BNBUSDT, XRPUSDT, SOLUSDT, DOGEUSDT, TRXUSDT, ADAUSDT, LINKUSDT, AVAXUSDT, SUIUSDT, LTCUSDT, BCHUSDT, HBARUSDT, NEARUSDT, UNIUSDT, DOTUSDT, APTUSDT, ARBUSDT, OPUSDT
TICKERS	18 US equities: NVDA, AAPL, GOOGL, MSFT, AMZN, AVGO, META, TSLA, LLY, WMT, AMD, V, XOM, JNJ, ORCL, COST, NFLX, CRM
CANONICAL_FREQS	15 intervals: 1s, 1m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M
SUPPORTED_STOCK_FREQS	1m, 5m, 15m, 30m, 1h, 1d, 1w, 1M
BINANCE_INTERVAL_* / FINNHUB_* / YFINANCE_*	Canonical ↔ provider interval maps and max lookbacks

Dataset

A pydantic BaseModel in hermes/core/dataset.py:

python

class Dataset(BaseModel):
    id: uuid.UUID          # default_factory=uuid4
    name: str
    version: str
    schema_ref: ...
    metadata: MetaData
    provenance: Provenance
    lineage: Lineage

The composable parse/normalize/validate/query methods and the Lineage/Provenance/MetaData/DataVersion/Result model classes are the target architecture and are being built out.

Feature registry (reference)

python

@feature(name, group, deps, compute)
def fn(...): ...

class LineageGraph:
    register_feature(name, group, deps, compute, fn)
    get_feature(name) -> dict | None
    get_group_features(group) -> list[str]
    resolve_group(group) -> TieredPlan
    save(path) / load(path)

class TieredPlan:
    tiers: list[list[str]]
    all_features: list[str]

Alpha status

Hermes is at v0.2.14. Connectors and features are actively tested (pytest with asyncio auto-mode; ruff + mypy in CI). Several core lifecycle modules remain placeholders while the platform matures.

← Previous

Features

Roadmap