Python API Reference

Complete reference for the Hermes Python API. All functions are importable from the top-level hermes module.


import hermes as hr

Fetching / Acquisition

🛠

The top-level hr.fetch, hr.fetch_raw, hr.ingest, hr.read, and hr.sync are scaffolded and currently return NotImplementedError. This section documents their intended signatures. For working acquisition today, use the connector classes directly — see Acquisition.

`hr.fetch(source, **kwargs) -> Result`

Acquire data from a registered connector (cached).


result = hr.fetch("world_bank", country_code="US", indicator_code="NY.GDP.MKTP.KD.ZG")
result = hr.fetch("fred", series_id="CPIAUCSL")
result = hr.fetch("binance", mode="future", endpoint="ohlcv", symbol="BTCUSDT", interval="1d")

Parameter	Type	Description
`source`	`str`	Connector name (see table below)
`**kwargs`		Connector-specific parameters

Registered connectors (intended): binance, finnhub, fred, gdelt, imf, opensanctions, public_data, sec, world_bank, yfinance

`hr.fetch_raw(source, **kwargs) -> Result`

Same as fetch() but bypasses the cache layer.

`hr.ingest(source, **kwargs) -> Result`

Fetch data and return with metadata attached.

`hr.read(path, **kwargs) -> Result`

Read a local file (CSV, Parquet, JSON, JSONL) into a Polars DataFrame.


result = hr.read("data.csv")
result = hr.read("data.parquet")
result = hr.read("data.json")

`hr.sync(source, **kwargs) -> Result`

Synchronize data incrementally using a SyncEngine.


result = hr.sync("world_bank", fetch_fn=my_fetch, interval="1h")

Data Operations

`hr.profile(data=None, path=None, source=None) -> MetaData`

Full statistical profile of a DataFrame or file. When using path, the file must be CSV or Parquet.


metadata = hr.profile(df)
metadata = hr.profile(path="data.csv")

`hr.inspect(data) -> InspectReport`

Quick inspection without full statistical scan.


info = hr.inspect(df)

`hr.get_freqs(data) -> list[str] | None`

Detect temporal frequency of columns.


freqs = hr.get_freqs(df)

`hr.date_ranges(data) -> list[dict] | None`

Detect min/max dates per temporal column.


ranges = hr.date_ranges(df)

`hr.anomaly_count(data, threshold=1.5) -> dict[str, int]`

Count IQR-based anomalies per numeric column.


anomalies = hr.anomaly_count(df, threshold=1.5)

`hr.parse(data, format=None, **kwargs) -> Result`

Parse a file, path, bytes, or string into a DataFrame. Format is auto-detected; see Parsing.


result = hr.parse("data.csv")          # Result; .data is the pl.DataFrame
result = hr.parse(path, format="json")

`hr.normalize(data, rules=None, report=False, context=None)`

Run normalization rules over data; returns the same container type as the input. With report=True, returns a NormalizationResult. See Normalization.


from hermes.normalization import NormalizeCountry
 
out = hr.normalize(df, rules=[NormalizeCountry("country")])

`hr.validate(data, rules=None, context=None) -> ValidationResult`

Run validation rules against a DataFrame. See Validation.


from hermes.validation import NotNull
 
report = hr.validate(df, rules=[NotNull("country_code")])

`hr.transform(data, fn=None, **kwargs) -> Result`

NOT IMPLEMENTED — raises NotImplementedError.

Datasets

`hr.Dataset(name, data_ref, data=None, ...)`

The core dataset abstraction.


ds = hr.Dataset(name="gdp", data_ref="gdp.csv", data=df)

Methods:

ds.load() — Load data from data_ref (CSV, JSON, JSONL, Parquet, XML, or sqlite://)
ds.inspect() — Quick inspection
ds.profile() — Full statistical profile
ds.save(path, format) — Write to disk (parquet/csv/json)
ds.export(format) — Export to bytes (parquet/csv/json) or dataframe
ds.to_polars() — Convert to Polars DataFrame
ds.to_arrow() — Convert to PyArrow Table
ds.to_pandas() — Convert to Pandas DataFrame
ds.metadata_info() — MetaData
ds.provenance_info() — Provenance
ds.lineage_info() — Lineage
ds.schema_info() — str | None (raises if no schema set)

`hr.list_datasets() -> Result`

NOT IMPLEMENTED — scaffolded.

`hr.get_dataset(dataset_id) -> Result`

NOT IMPLEMENTED — scaffolded.

`hr.search_datasets(query) -> Result`

NOT IMPLEMENTED — scaffolded.

Entities

`hr.resolve_entity(query, entity_type=None)`

Dispatch by entity_type to resolve_company/resolve_country, both of which are NOT IMPLEMENTED (raise NotImplementedError). Low-level helpers (get_cik, iso3_to_iso2, check_iso3) work — see Entities.

`hr.resolve_country(query) -> Result`

NOT IMPLEMENTED — raises NotImplementedError.

`hr.resolve_company(query) -> Result`

NOT IMPLEMENTED — raises NotImplementedError.

Schemas

`hr.get_schema(name, version=None) -> Result`

NOT IMPLEMENTED — scaffolded.

`hr.register_schema(schema) -> Result`

NOT IMPLEMENTED — scaffolded.

`hr.compare_schema(schema_a, schema_b) -> Result`

NOT IMPLEMENTED — scaffolded.

`hr.migrate(data, from_schema, to_schema) -> Result`

NOT IMPLEMENTED — scaffolded.

Storage

`hr.save(data, path, format="parquet") -> Result`

NOT IMPLEMENTED — scaffolded. Use Dataset.save() instead.

`hr.load(path) -> Result`

NOT IMPLEMENTED — scaffolded. Use Dataset + Dataset.load() instead.

`hr.query(data, **kwargs) -> Result`

NOT IMPLEMENTED — scaffolded.

`hr.materialize(data, target) -> Result`

NOT IMPLEMENTED — scaffolded.

Configuration

`hr.configure(api_keys=None, **settings) -> HermesConfig`

NOT IMPLEMENTED — raises NotImplementedError.

`hr.get_config() -> HermesConfig`

NOT IMPLEMENTED — raises NotImplementedError.

Credentials

Credential storage is implemented and persisted to ~/.hermes-plt/credentials.json:


hr.set_cred("fred", "api_key_value")
hr.get_cred("fred")                     # -> "api_key_value"
hr.has_cred("fred")                     # -> True
hr.list_creds()                         # -> ["fred"]
hr.delete_cred("fred")

Error Hierarchy


from hermes import (
    HermesError,           # Base exception
    AcquisitionError,      # Failed to acquire data
    ParseError,            # Failed to parse data
    SchemaError,           # Schema-related error
    NormalizationError,    # Failed to normalize data
    ValidationError,       # Data failed validation
    StorageError,          # Storage operation failed
    QueryError,            # Query execution failed
    ConfigError,           # Configuration error
    ConnectorNotFoundError,# Unknown connector
    AuthenticationError,   # Missing/invalid credentials
)

Core Models

`Result`


result = hr.fetch("world_bank", ...)
 
result.status       # "success" | "warning" | "partial" | "failure"
result.data         # The fetched data
result.metadata     # Optional metadata dict
result.statistics   # Optional statistics dict
result.errors       # List of ResultError
result.warnings     # List of warning strings
 
result.is_success()     # True if no errors
result.is_failure()     # True if status=failure or errors present
result.raise_if_failure()  # Raises RuntimeError if errors

A Result is returned by hr.parse() and by the (scaffolded) fetch/ingest/read/sync wrappers.

`MetaData`

See Metadata for full field reference.

`Provenance`


provenance = ds.provenance_info()
provenance.source          # str: data source
provenance.endpoint        # str | None: API endpoint
provenance.retrieved_at    # datetime | None
provenance.connector       # str | None: connector name
provenance.connector_version  # str | None
provenance.raw_checksum    # str | None
provenance.parser_version / normalizer_version / schema_version  # str | None

`Lineage`


lineage = ds.lineage_info()
lineage.steps              # list[LineageStep]
lineage.trace()            # -> list[LineageStep]
lineage.last_operation()   # -> LineageStep | None

`LineageStep`


step = lineage.steps[0]
step.operation     # str: operation name
step.input_ref     # str | None: input reference
step.output_ref    # str | None: output reference
step.timestamp     # datetime
step.params        # dict: operation parameters

`DataVersion`


from hermes.core.versioning import DataVersion
 
version = DataVersion(
    content_hash="abc123",
    schema_hash="def456",
    parent_version="v0.0.1",
)
version.is_compatible(other_version)  # True if both have same schema_hash