docs/taxonomy.md

The bundled general-economy taxonomy

The default policy in RANGE is a conservative, offline taxonomy for economic and financial-news screening. It is not a portfolio definition and it is not a sentiment or trading model.

Decision layers

Each article is processed through four traceable layers:

1. Observation — literal text spans are matched by effective-dated aliases, normalized phrases, context-qualified acronyms, or conjunction rules.
2. Identity resolution — catalog observations are accepted, rejected, or left unresolved at the article timestamp.
3. Evidence construction — accepted and unresolved observations become evidence paths with reason codes and relationship lineage.
4. Decision — the article receives an admissibility status and one decision for each broad exposure family.

The taxonomy fingerprint hashes the loaded configuration and catalogs. A result is reproducible only when the text, timestamp, package version, and taxonomy fingerprint are all retained.

General-economy scope

The bundled lexical catalog covers these maintained areas:

• central banks and monetary policy;
• consumer, producer, and consumption-price inflation;
• payrolls, unemployment, claims, job openings, participation, and wages;
• GDP, consumption, production, business surveys, confidence, housing, and orders;
• Treasury yields, the yield curve, credit spreads, lending standards, and the dollar;
• energy and industrial commodity prices;
• fiscal policy, debt-limit events, shutdowns, tariffs, and trade controls;
• supply-chain disruptions and business-cycle language;
• financial stability, banking stress, volatility, sovereign risk, and sanctions;
• securities and banking regulation;
• named economic sectors; and
• common company-event phrases.

The broad categories are intentionally finite. Exact phrase presence does not prove economic causality, and absence does not prove that an article is economically unimportant.

Exposure model

The public alpha has four broad exposure families:

family	interpretation
EXPOSURE:SP500	S&P 500 benchmark evidence
EXPOSURE:NASDAQ100	Nasdaq-100 benchmark evidence
EXPOSURE:RUSSELL2000	Russell 2000 benchmark evidence
MARKET_WIDE	economic or market-wide evidence not limited to one benchmark

The entity catalog contains only the three named indexes and their common broad ETF proxies, SPY, QQQ, and IWM. It does not bundle a leveraged-ETF universe, a complete security master, or historical constituents.

A direct index or broad-ETF alias can complete a benchmark-specific relevance path. A maintained macroeconomic or market-wide lexical rule can complete a MARKET_WIDE path. Sector and company-event phrases are retained as financial context but do not guess a security or broad benchmark when no explicit relationship exists.

Direction neutrality

RANGE answers whether evidence is connected to a maintained economic or market concept. It does not infer whether the evidence is:

• bullish or bearish;
• temporary or persistent;
• already priced in;
• material enough to trade; or
• favorable for a long, short, leveraged, or inverse instrument.

A downstream application may map broad exposures into its own current holdings or watchlist. Keeping that mapping outside the default taxonomy prevents the package from silently becoming stale when a portfolio changes.

Exact matching contract

The normalizer applies the package's frozen per-code-point NFKC and casefold behavior, normalizes supported dash and separator variants, standardizes apostrophes, collapses Python whitespace, and checks token boundaries. It does not use stemming, edit distance, fuzzy correction, embeddings, or a language model.

Selected short acronyms such as CPI, GDP, PPI, PMI, SEC, and Fed require case or nearby context where collision risk is material. SPY also requires financial context so ordinary uses of “spy” do not become ETF evidence.

Effective dates

Every article requires a timestamp. Entity aliases and relationships are evaluated at that time using half-open validity intervals [valid_from, valid_to).

The QQQ catalog demonstrates why this matters: the canonical fund remains continuous, while historical and current product-name aliases have non-overlapping validity periods. A ticker may remain valid while a product or issuer name changes.

ISO 8601 timestamps with an explicit UTC offset are recommended. Naive values use the documented America/New_York convention.

Inspect the taxonomy

from range_curate.examples.general_economy import GeneralEconomyTaxonomy

taxonomy = GeneralEconomyTaxonomy()

print(taxonomy.version)
print(taxonomy.fingerprint)
print(taxonomy.describe())
print(taxonomy.entity_ids)
print(taxonomy.lexical_rule_ids)

Copy and edit the complete bundle

from range_curate.examples.general_economy import RelevanceEngine, copy_default_taxonomy

path = copy_default_taxonomy("my_taxonomy")
# Edit my_taxonomy/taxonomy.yml and my_taxonomy/catalogs/*.yml.
engine = RelevanceEngine.from_yaml(path)

The copied structure is:

my_taxonomy/
├── taxonomy.yml
└── catalogs/
    ├── entities.yml
    └── lexical.yml

Unknown fields fail closed. Existing files are not overwritten unless overwrite=True is explicit.

Add rules in Python

Taxonomy.extend() and subclass configuration are add-only conveniences. They return new immutable taxonomy objects and never mutate the bundled default.

from range_curate.examples.general_economy import GeneralEconomyTaxonomy


def add_indicator(builder):
    builder.add_lexical_rule(
        rule_id="regional-manufacturing-survey",
        entity_concept="macroeconomic_indicator",
        tag_type="macroeconomic",
        phrases=("regional manufacturing survey",),
        target_id="MACRO:REGIONAL_MANUFACTURING",
        market_wide_authorized=True,
        source_id="my-project",
    )


custom = GeneralEconomyTaxonomy().extend(add_indicator)

Use an editable YAML copy when existing rules, aliases, dates, relationships, ranking settings, or exposure membership must be removed or changed.

Provenance and review discipline

Each maintained row has a stable rule_id or alias_id and a source_id. The YAML also records source URLs for human review, but source URLs are not fetched during inference and are not treated as live guarantees.

Before changing the bundled taxonomy:

1. state the intended concept and false-positive risk;
2. add positive, negative, boundary, and effective-date tests;
3. verify rich, compact-list, and Arrow agreement;
4. record the new catalog version and source-as-of date; and
5. treat the resulting fingerprint change as a new decision policy.

Limitations

The default taxonomy does not provide:

• exhaustive coverage of economic language;
• entity linking for arbitrary companies;
• licensed constituent histories;
• current holdings or portfolio mappings;
• automatic taxonomy maintenance;
• sentiment, causality, magnitude, or horizon estimates; or
• investment advice.

The alpha is designed to be inspectable and conservative. Broader recall should be added explicitly rather than hidden behind approximate matching.