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



```python

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



```python

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:

```text

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.

```python

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.