Spaces:
Running on Zero
Running on Zero
| # 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. | |