Configuration

Hermes configuration covers API keys, cache settings, and runtime options.

Environment Variables

Create a .env file in your project root to record your API keys:

# FRED (Federal Reserve Economic Data)
FRED_API=your_api_key
 
# Finnhub (financial data)
FINNHUB_API=your_api_key
 
# OpenSanctions
OPEN_SANCTIONS_API=your_api_key
 
# SEC EDGAR (User-Agent identification)
SEC_USERNAME=Your Name
SEC_EMAIL=your@email.com

These are the documented convention (see .env.example). Hermes does not auto-load .env files yet. Connectors read their keys from the credential manager at construction time, so register the value first:

import hermes as hr
from hermes.connectors import FRED, FINNHUB, OpenSanction, SECEDGAR
 
hr.set_cred("fred", "your_key")
hr.set_cred("finnhub", "your_key")
hr.set_cred("opensanction", "your_key")
hr.set_cred("sec_username", "Your Name")
hr.set_cred("sec_email", "your@email.com")
 
fred = FRED()
finnhub = FINNHUB()
sanctions = OpenSanction()
sec = SECEDGAR()

The credential manager API: hr.set_cred(name, value), hr.get_cred(name), hr.has_cred(name), hr.list_creds(), hr.delete_cred(name). Values are persisted locally to ~/.hermes-plt/credentials.json (mode 0600); nothing is logged or exported.

On a fresh install the store must exist before hr.set_cred/hr.get_cred work — until ~/.hermes-plt/credentials.json is present they raise CredentialStorageError. The CLI’s cred command was removed in the Rust CLI rewrite, so initialize the file first (it can simply contain {}).

Required Variables

Connectors Without API Keys

These connectors work without any configuration:

• World Bank — world_bank
• IMF — imf
• Binance — binance
• YFinance — yfinance
• GDELT — gdelt (stub)
• Public datasets — public_data (bundled CSVs)

Programmatic Configuration

hr.configure() and hr.get_config() are scaffolded and currently raise NotImplementedError — use the credential manager (hr.set_cred / hr.get_cred) for API keys today.

Cache Configuration

The cache stores Parquet files on disk. Default location: ~/.hermes_cache/raw/.

Default Settings

Custom Cache

from hermes.acquisition import RawCache
 
cache = RawCache(cache_dir="/my/custom/cache")

Or pass cache=None to a connector to bypass the disk cache entirely:

from hermes.connectors import World_bank
 
wb = World_bank(cache=None)  # no caching

Per-Source TTLs

Connectors use different cache TTLs:

Managing the Cache

from hermes.acquisition import RawCache
 
cache = RawCache()
 
# View statistics
stats = cache.stats()
print(stats["total_files"])
print(stats["by_source"])
print(stats["hit_rate"])
 
# Clear all cached data
cache.clear()
 
# Clear only old entries
from datetime import timedelta
cache.clear(older_than=timedelta(days=7))

Sync State

Incremental sync state was previously persisted at ~/.hermes/sync/<source>.json. The SyncEngine/SyncState layer is currently being reworked — it is not yet importable in this version.

Scheduler Configuration

The scheduler runs jobs on a background thread.

Schedule Specs

Cron Fields

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Cron supports:

• Wildcards: *
• Ranges: 1-5
• Steps: */5, 1-30/5
• Lists: 1,3,5