Skip to Content
Quickstart

Quickstart

Get Hermes running in under 5 minutes. This guide walks you through installation, basic configuration, and your first data pipeline.

Install

Hermes requires Python 3.11 or newer. Install from PyPI:

pip install hermes-plt

Verify the installation:

hermes --help

The CLI currently ships four commands — fetch, inspect, dataset, entity — which parse but are not implemented yet. Profiling from the terminal is not available in this release; use the Python API below.

Basic Usage

Profile a local file

The fastest way to see Hermes in action — profile any CSV or Parquet file:

import hermes as hr
 
# Profile a CSV file directly
report = hr.profile(path="data.csv")
 
print(report.row_count)
print(report.column_count)
for col in report.columns:
    print(f"{col.name}: {col.dtype}, nulls={col.null_count}, unique={col.unique_count}")

Profile from Python — the terminal equivalent is not yet available:

report = hr.profile(path="data.csv")

Read and inspect data

import hermes as hr
import polars as pl
 
# Read a file into a DataFrame
df = pl.read_csv("gdp.csv")
 
# Quick inspection
info = hr.inspect(df)
print(f"rows: {info.row_count}, columns: {info.column_count}")
for col_name, col_type in info.columns:
    print(f"  {col_name}: {col_type}")

Work with the Dataset object

The Dataset is Hermes’ core abstraction — it holds your data alongside its metadata, provenance, and lineage:

import hermes as hr
import polars as pl
 
df = pl.read_csv("gdp.csv")
 
# Create a Dataset
ds = hr.Dataset(
    name="gdp",
    data_ref="gdp.csv",
    data=df,
)
 
# Profile it (populates metadata)
ds.profile()
 
# Inspect the data
report = ds.inspect()
print(f"rows: {report.row_count}, columns: {report.column_count}")
 
# Access metadata
print(ds.metadata_info())
print(ds.provenance_info())
print(ds.lineage_info())

Export data

# Save to different formats
ds.save("output/", format="parquet")   # writes output/gdp.parquet
ds.save("output/", format="csv")       # writes output/gdp.csv
ds.save("output/", format="json")      # writes output/gdp.json
 
# Or export to raw bytes
csv_bytes = ds.export("csv")
parquet_bytes = ds.export("parquet")

Interoperate with your stack

# Convert to any format your tools expect
polars_df = ds.to_polars()   # polars.DataFrame
arrow_tbl = ds.to_arrow()    # pyarrow.Table
pandas_df = ds.to_pandas()   # pandas.DataFrame

Connectors

Hermes ships with 10 source connectors that share a common disk cache and retry layer. They are synchronous; each fetch() caches its result by default.

World Bank (no API key required)

from hermes.connectors import World_bank
 
wb = World_bank()  # uses the shared disk cache (~/.hermes_cache/raw)
 
df = wb.fetch(
    country_code="US",
    indicator_code="NY.GDP.MKTP.KD.ZG",
)
print(df.head())

FRED (requires API key)

Register the key first, then construct the connector — connectors read credentials from the credential manager at instantiation time:

import hermes as hr
from hermes.connectors import FRED
 
hr.set_cred("fred", "your_fred_key")
 
fred = FRED(api="your_fred_key")
df = fred.fetch(series_id="CPIAUCSL")  # Consumer Price Index
print(df.head())

Binance (no API key required)

from hermes.connectors import Binance
 
b = Binance()
 
# Single request (cached): 30 daily spot candles
df = b.fetch(mode="spot", endpoint="ohlcv", symbol="BTCUSDT", interval="1d", limit=30)
print(df.head())
 
# Multi-year history (future market)
history = b.fetch_history(symbol="BTCUSDT", interval="1d", market="future", years=2)
print(history.head())

See Acquisition and the Python API for the full connector list and signatures.

Next Steps

Last updated on
IntroductionInstallation