Skip to Content
COREEntities

Entities

The entities module provides country and company resolution primitives — mapping between ISO codes, ticker symbols, CIK numbers, and human-readable names.

Status: helper functions (countries, iso3_to_iso2, check_iso3, get_cik) and the Entity/EntityMatch models are implemented. The top-level hr.resolve_* functions and EntityRegistry are scaffolded and raise NotImplementedError.

Top-Level API

import hermes as hr
 
# General entity resolution -- dispatched by entity_type
result = hr.resolve_entity("Apple Inc.", entity_type="company")
 
# NOT IMPLEMENTED -- resolve_country/resolve_company raise NotImplementedError
result = hr.resolve_country("USA")
result = hr.resolve_company("AAPL")

hr.resolve_entity(query, entity_type) routes to resolve_company/resolve_country when entity_type is "company"/"country" — both of which currently raise NotImplementedError. These are scheduled for implementation; the low-level helpers below already provide country/code and ticker→CIK lookup.

Countries

countries — ISO-3 Code List

A list of 249 ISO-3 country codes:

from hermes.entities.countries import countries
 
len(countries)      # 249
countries[:5]       # ['AFG', 'ALA', 'ALB', 'DZA', 'ASM']

iso3_to_iso2(iso3_code) -> str

Convert ISO-3 to ISO-2 country code:

from hermes.entities.countries import iso3_to_iso2
 
iso3_to_iso2("USA")  # -> "US"
iso3_to_iso2("GBR")  # -> "GB"
iso3_to_iso2("JPN")  # -> "JP"

Returns "Not Found" for an invalid code.

check_iso3(code)

Validate an ISO-3 code. Raises RuntimeError if invalid:

from hermes.entities.countries import check_iso3
 
check_iso3("USA")  # passes
check_iso3("XYZ")  # RuntimeError: The XYZ is not iso3

Companies

get_cik(ticker) -> str

Resolve a stock ticker to its SEC CIK number:

from hermes.entities.companies import get_cik
 
get_cik("AAPL")   # -> "CIK0000320193"
get_cik("ZZZZ")   # -> "Not Found"

Uses the sec-cik-mapper library to map tickers (case-insensitive) to CIK numbers.

Entity Models

Entity

from hermes.entities.models import Entity
 
entity = Entity(
    id="us_001",
    name="United States",
    entity_type="country",
    country="US",
    identifiers={"iso3": "USA", "iso2": "US"},
    aliases=["US", "United States of America"],
)

EntityMatch

from hermes.entities.models import EntityMatch
 
match = EntityMatch(entity=entity, score=0.95, match_type="exact")

Used by resolvers to return ranked matches for entity queries.

Resolver

Abstract base class for entity resolvers. Implement resolve, identify, and match:

from hermes.entities import Resolver
from hermes.entities.models import Entity, EntityMatch
 
class MyResolver(Resolver):
    def resolve(self, query: str) -> Entity | None: ...
    def identify(self, data: object) -> object: ...
    def match(self, query: str, threshold: float = 0.8) -> list[EntityMatch]: ...

Resolver cannot be instantiated directly — use a concrete subclass.

EntityRegistry

NOT IMPLEMENTED — all methods raise NotImplementedError. The intended interface:

from hermes.entities import EntityRegistry
 
registry = EntityRegistry()
registry.register("company", my_resolver)  # my_resolver: Resolver
registry.get("company")                    # -> Resolver | None
registry.resolve("AAPL", entity_type="company")
registry.list_types()                      # -> list[str]
Last updated on
MetadataDatasets