Publish-ready RANGE snapshot

.gitattributes

@@ -0,0 +1,2 @@
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.so filter=lfs diff=lfs merge=lfs -text

CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable package changes are recorded here. The package follows semantic
+versioning and uses Python's pre-release version syntax.
+
+## 0.1.0a1 — release candidate, not published
+
+### Added
+
+- The public `range_news` Python namespace and **RANGE** product name: Rapid Analysis
+  of News for the General Economy.
+- An exact CPU/Rust path for rich predictions, compact list screening, and Arrow screening.
+- A conservative, offline general-economy taxonomy covering monetary policy, inflation,
+  labor markets, growth, rates, credit, fiscal policy, trade, supply disruptions,
+  financial stability, regulation, sectors, company events, and broad market benchmarks.
+- Deterministic evidence lineage, effective dates, taxonomy fingerprints, explanations,
+  ranking, and editable taxonomy copies.
+- Wheel and source-distribution verification on Windows and Linux CI.
+- Runnable README examples with visible output.
+- A Space-ready Gradio demo under `app/` with highlighted evidence, evidence JSON,
+  batch screening, downloadable outputs, named API endpoints, a multi-stage Docker
+  build, and a deterministic offline export manifest.
+- Separate deployment exports for local Docker and free Gradio/ZeroGPU hosting. The
+  hosted export vendors the runtime payload from an inspected CPython 3.10
+  manylinux2014 wheel while keeping prediction on the compiled CPU/Rust path.
+- CI validation and a Linux container smoke test for the future Hugging Face Space.
+
+### Changed
+
+- The project is now named **RANGE** throughout its distribution, Python namespace,
+  native module, documentation, deployment identifiers, and demo.
+- The README now leads with the job-to-be-done, a working result, intended users,
+  an architecture overview, a mechanism-level speed explanation, API selection
+  guidance, and carefully qualified benchmark context.
+- The Space demo now separates article relevance from supported exposure, distinguishes
+  unresolved evidence paths visually, and includes a verified private-deployment
+  runbook.
+- The public package identity, examples, and documentation are no longer tied to the
+  Attention2Alpha project or a particular leveraged-ETF portfolio. This presentation
+  pass leaves the established default taxonomy semantics unchanged.
+- The package version is `0.1.0a1`, explicitly identifying a research alpha.
+- The hosted demo now rejects oversized or malformed requests before inference,
+  shares one bounded execution queue across its public endpoints, and hides internal
+  error details in production.
+- Evidence downloads now omit screened article text, retain a SHA-256 identifier and text
+  lengths, live in Gradio's managed cache, and become eligible for best-effort cleanup
+  after five minutes.
+- Hosted dependencies, Docker base images, and the Dockerfile frontend are pinned for
+  reproducible deployment builds. Managed networks can supply a trusted build root as
+  a temporary secret without disabling TLS verification.
+
+### Not included
+
+- No GPU backend.
+- No public or production hosted service, model download, live-data integration,
+  trading recommendation, release tag, or package-index publication.

CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "Please cite an archived release when this software supports published work."
+title: "RANGE: Rapid Analysis of News for the General Economy"
+type: software
+version: "0.1.0a1"
+authors:
+  - family-names: Ferrell
+    given-names: Brian
+license: MIT
+keywords:
+  - financial news
+  - economic news
+  - information retrieval
+  - taxonomy
+  - reproducible research

Cargo.lock

@@ -0,0 +1,1017 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "const-random",
+ "getrandom 0.3.4",
+ "once_cell",
+ "version_check",
+ "zerocopy",
+]
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "arrow-array"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e5f6adeffdf587d7a31db5d2266189624b526730cd3627f9ff9fedae97ad584"
+dependencies = [
+ "ahash",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "chrono",
+ "chrono-tz",
+ "half",
+ "hashbrown",
+ "libc",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-buffer"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "097d193003ce7995d5d087089069ec2a6e0187faf5a6f8c9f38af2645d987182"
+dependencies = [
+ "bytes",
+ "half",
+ "num-bigint",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-cast"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "635c9c635668ad26adf76cce8fb276c4be7cf06e63bd516de7da514f9680ee53"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-ord",
+ "arrow-schema",
+ "arrow-select",
+ "atoi",
+ "base64",
+ "chrono",
+ "comfy-table",
+ "half",
+ "lexical-core",
+ "num-traits",
+ "ryu",
+]
+
+[[package]]
+name = "arrow-data"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ba2f832eaeca24b8f26143dba750e42ee4ab51cf7d65e701ca9607cfda9f358"
+dependencies = [
+ "arrow-buffer",
+ "arrow-schema",
+ "half",
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "arrow-ord"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c900759f3bd8354fd4196bc4403eee846894dc2adf66b4225472006a0bf18c5"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "arrow-select",
+]
+
+[[package]]
+name = "arrow-schema"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10fab8d4563491417ba801fab29d205104d20d4bdf37bda6cd1cf425cff598cd"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "arrow-select"
+version = "59.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc58569193c2525915f3cc6310edba3792f1200f65d6e9ed330aa33e691493b8"
+dependencies = [
+ "ahash",
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-data",
+ "arrow-schema",
+ "num-traits",
+]
+
+[[package]]
+name = "atoi"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f28d99ec8bfea296261ca1af174f24225171fea9664ba9003cbebee704810528"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ad534f4357a5264cce5019c989cf66a4f0dc4e0d1b1d15f8aacec0ff7360273"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "js-sys",
+ "num-traits",
+ "wasm-bindgen",
+ "windows-link",
+]
+
+[[package]]
+name = "chrono-tz"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6139a8597ed92cf816dfb33f5dd6cf0bb93a6adc938f11039f371bc5bcd26c3"
+dependencies = [
+ "chrono",
+ "phf",
+]
+
+[[package]]
+name = "comfy-table"
+version = "7.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "958c5d6ecf1f214b4c2bbbbf6ab9523a864bd136dcf71a7e8904799acfe1ad47"
+dependencies = [
+ "unicode-segmentation",
+ "unicode-width",
+]
+
+[[package]]
+name = "const-random"
+version = "0.1.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "87e00182fe74b066627d63b85fd550ac2998d4b0bd86bfed477a0ae4c7c71359"
+dependencies = [
+ "const-random-macro",
+]
+
+[[package]]
+name = "const-random-macro"
+version = "0.1.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9d839f2a20b0aee515dc581a6172f2321f96cab76c1a38a4c584a194955390e"
+dependencies = [
+ "getrandom 0.2.17",
+ "once_cell",
+ "tiny-keccak",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5181e0de7b61eb03a81e347d6dd8797bae9da5146707b51077e2d71a54ec0ceb"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17"
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "either"
+version = "1.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "252afb9ae5eaa683babdc6a068b3f5726eb19e05070c731f9b2a23a7c3e8ed34"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d45db016d36b838f563236e9193d0ee6ce38f3f68b6c94e914b4929c96bbb890"
+
+[[package]]
+name = "futures-core"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"
+
+[[package]]
+name = "futures-task"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"
+
+[[package]]
+name = "futures-util"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "num-traits",
+ "zerocopy",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.17.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07aa2048142242915a31d35844fb311e0e53fcca590c3a0a40dcf1b841fa09eb"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "js-sys"
+version = "0.3.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "lexical-core"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d8d125a277f807e55a77304455eb7b1cb52f2b18c143b60e766c120bd64a594"
+dependencies = [
+ "lexical-parse-float",
+ "lexical-parse-integer",
+ "lexical-util",
+ "lexical-write-float",
+ "lexical-write-integer",
+]
+
+[[package]]
+name = "lexical-parse-float"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52a9f232fbd6f550bc0137dcb5f99ab674071ac2d690ac69704593cb4abbea56"
+dependencies = [
+ "lexical-parse-integer",
+ "lexical-util",
+]
+
+[[package]]
+name = "lexical-parse-integer"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a7a039f8fb9c19c996cd7b2fcce303c1b2874fe1aca544edc85c4a5f8489b34"
+dependencies = [
+ "lexical-util",
+]
+
+[[package]]
+name = "lexical-util"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2604dd126bb14f13fb5d1bd6a66155079cb9fa655b37f875b3a742c705dbed17"
+
+[[package]]
+name = "lexical-write-float"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50c438c87c013188d415fbabbb1dceb44249ab81664efbd31b14ae55dabb6361"
+dependencies = [
+ "lexical-util",
+ "lexical-write-integer",
+]
+
+[[package]]
+name = "lexical-write-integer"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "409851a618475d2d5796377cad353802345cba92c867d9fbcde9cf4eac4e14df"
+dependencies = [
+ "lexical-util",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "log"
+version = "0.4.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-bigint"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93e7820bc0a80a0238e650327316f929ba18d5be054b647490a3a6a339f3e7c0"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+ "libm",
+]
+
+[[package]]
+name = "numpy"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a5b15d63a5ff39e378daed0e1340d3a5964703ea9712eb09a0dc66fade996f4"
+dependencies = [
+ "half",
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "phf"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "913273894cec178f401a31ec4b656318d95473527be05c0752cc41cdc32be8b7"
+dependencies = [
+ "phf_shared",
+]
+
+[[package]]
+name = "phf_shared"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06005508882fb681fd97892ecff4b7fd0fee13ef1aa569f8695dae7ab9099981"
+dependencies = [
+ "siphasher",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
+dependencies = [
+ "chrono",
+ "chrono-tz",
+ "indexmap",
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-arrow"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d5ddf226a2dbf7607570d0657c2bf6fbe299208368b2914f3dd7e7ba0b57688"
+dependencies = [
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-cast",
+ "arrow-data",
+ "arrow-schema",
+ "arrow-select",
+ "chrono",
+ "chrono-tz",
+ "half",
+ "indexmap",
+ "numpy",
+ "pyo3",
+ "thiserror",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "range_news_native"
+version = "0.1.0"
+dependencies = [
+ "aho-corasick",
+ "arrow-array",
+ "arrow-schema",
+ "pyo3",
+ "pyo3-arrow",
+ "rayon",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rayon"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "siphasher"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tiny-keccak"
+version = "2.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c9d3793400a45f954c52e73d068316d76b6f4e36977e3fcebb13a2721e80237"
+dependencies = [
+ "crunchy",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
+
+[[package]]
+name = "unicode-width"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.4+wasi-0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.127"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.127"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.127"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.127"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "wit-bindgen"
+version = "0.57.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "556764e583adb45a9f8d413c2a147fa7e8d821e48e12b14fd560b607998b75eb"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ab42fc20575779bd240faa45f94a74256f755c0fa9e89f0ede20d91d0cdfc1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]

Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "range_news_native"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.88"
+publish = false
+license = "MIT"
+description = "Native engine for RANGE financial-news relevance screening"
+
+[lib]
+name = "_native"
+path = "rust/lib.rs"
+crate-type = ["cdylib"]
+
+[dependencies]
+aho-corasick = "1.1.5"
+arrow-array = "59"
+arrow-schema = "59"
+pyo3 = { version = "0.29.2", features = ["extension-module"] }
+pyo3-arrow = { version = "0.19.0", default-features = false }
+rayon = "1.12"
+
+[profile.release]
+lto = "fat"
+codegen-units = 1
+strip = "symbols"

DEPLOYMENT.md

@@ -0,0 +1,202 @@
+# Run RANGE locally or deploy it free on Hugging Face
+
+RANGE supports two deployments from the same Gradio app:
+
+| Route | Best for | Runtime |
+| --- | --- | --- |
+| Local Docker | Private local use and a portable container | Docker with the compiled CPU/Rust engine |
+| Private Hugging Face Space | A shareable demo without a paid plan | Gradio on the free ZeroGPU runtime, with the same CPU/Rust engine |
+
+The Hugging Face route does **not** turn RANGE into a GPU application. Its real
+`/analyze` and `/batch` endpoints remain on CPU and never request a GPU allocation.
+The app contains one unused `@spaces.GPU` function solely because the free ZeroGPU
+runtime requires a decorated function.
+
+Free ZeroGPU hosting is currently available to eligible personal accounts in good
+standing, with a verified email, an account older than 30 days, and no more than two
+hosted ZeroGPU Spaces. Hugging Face can change these limits. See the
+[ZeroGPU documentation](https://huggingface.co/docs/hub/spaces-zerogpu) before a new
+deployment.
+
+## Prepare the repository
+
+Run these commands from `dataset/news_relevance/range_news` on the `codex` branch.
+The existing project environment is sufficient for validation:
+
+```powershell
+conda activate attention2alpha
+python app/validate_space.py
+python app/export_space.py `
+  --target docker `
+  --output build/huggingface-space `
+  --force
+```
+
+The exporter writes only below `build/` and replaces a directory only when its
+manifest proves that it is an earlier RANGE export.
+
+## Route A: run the Docker app locally
+
+```powershell
+docker build `
+  --tag range-news-space:0.1.0a1 `
+  build/huggingface-space
+
+docker run --rm --name range-news-space `
+  --publish 127.0.0.1:7860:7860 `
+  range-news-space:0.1.0a1
+```
+
+Open `http://127.0.0.1:7860`. Stop the container with `Ctrl+C`.
+
+The Docker bundle is self-contained source: it builds the Rust extension, installs
+the package and Gradio, and runs as an unprivileged user. It does not need a Hugging
+Face account or network access for inference.
+
+If downloads fail with an `UnknownIssuer` certificate error on a managed network,
+export that network's trusted root certificate as a PEM file and add
+`--secret "id=build_ca,src=C:\path\to\trusted-root.pem"` to the Docker build command.
+The certificate is available only while dependencies download and is not copied into
+the image. Do not disable TLS verification or add a trusted-host exception.
+
+## Route B: build the free Hugging Face bundle
+
+Hugging Face does not compile the Rust extension for this route. Export the portable
+CPython 3.10 manylinux2014 wheel from the Docker build first:
+
+```powershell
+docker build `
+  --platform linux/amd64 `
+  --target wheel-export `
+  --output "type=local,dest=build/manylinux2014-wheel" `
+  build/huggingface-space
+
+$Wheels = @(Get-ChildItem `
+  -LiteralPath build/manylinux2014-wheel `
+  -Filter "range_news-0.1.0a1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl")
+
+if ($Wheels.Count -ne 1) {
+  throw "Expected exactly one portable RANGE x86_64 wheel."
+}
+$Wheel = $Wheels[0]
+
+python app/export_space.py `
+  --target zerogpu `
+  --wheel $Wheel.FullName `
+  --output build/huggingface-zerogpu-space `
+  --force
+```
+
+The second export contains Gradio Space metadata, the app, package documentation and
+source, and a runtime copy extracted from the validated wheel. Gradio Spaces install
+`requirements.txt` before copying repository files, so a relative wheel reference
+cannot work during their build. Vendoring the inspected wheel payload keeps the build
+self-contained without publishing the package and makes the native extension available
+after the source copy. The requirements file installs RANGE's small Python
+dependencies; the platform supplies Gradio, `spaces`, and `huggingface_hub`.
+
+Before uploading, inspect `build/huggingface-zerogpu-space`. Do not add credentials,
+private dataset rows, licensed articles, caches, or machine-specific paths. A public
+Space exposes this bundle as a public repository, including the app source, bundled
+RANGE source and native runtime, package documentation, and default taxonomy. Review
+the uploaded revision history as well as the latest files before changing visibility.
+
+## Create and upload the private Space
+
+Use a small deployment environment to keep Hub tooling separate from the research
+environment. Create it once; skip the first command when it already exists:
+
+```powershell
+conda create --name range-news-hf-deploy --yes python=3.10
+conda activate range-news-hf-deploy
+python -m pip install `
+  "huggingface_hub>=1.16,<2" `
+  "gradio-client==2.6.1" `
+  "pip-system-certs>=5,<6"
+hf auth login
+hf auth whoami --format json
+```
+
+`pip-system-certs` lets the Python CLI use the Windows certificate store, including
+institution-managed certificate authorities.
+
+Create the private Gradio Space on the free ZeroGPU hardware and upload the prepared
+directory:
+
+```powershell
+$SpaceId = "Brianferrell787/range-news"
+
+hf repos create $SpaceId `
+  --type space `
+  --sdk gradio `
+  --flavor zero-a10g `
+  --private
+
+hf upload $SpaceId build/huggingface-zerogpu-space . `
+  --repo-type space `
+  --commit-message "Deploy private RANGE 0.1.0a1 demo"
+```
+
+Do not run the upload if creation fails. For an existing Space, first verify that its
+repository is private, its SDK is Gradio, and its hardware is ZeroGPU.
+
+## Verify the live deployment
+
+```powershell
+hf spaces wait $SpaceId --timeout 30m
+hf spaces logs $SpaceId --build -n 200
+hf spaces logs $SpaceId -n 200
+hf spaces info $SpaceId --expand sdk,runtime --format json
+```
+
+Open `https://huggingface.co/spaces/Brianferrell787/range-news` and test all three
+single-article examples plus the batch example. The Space can sleep when idle, so the
+first request may include a cold start.
+
+Private API calls use the token already stored by `hf auth login`:
+
+```python
+from gradio_client import Client
+from huggingface_hub import get_token
+
+client = Client("Brianferrell787/range-news", token=get_token())
+client.view_api()
+```
+
+The generated `agents.md` points coding agents to the API schema, which lists the
+named `/analyze` and `/batch` endpoints.
+
+## Privacy and performance boundaries
+
+- Do not add an HF token as a Space secret; RANGE needs no runtime credential.
+- Text submitted to the hosted demo is processed on Hugging Face infrastructure. Do
+  not submit confidential or unlicensed material.
+- The interface and named API endpoints reject more than 100 rows, more than 20,000
+  characters or 80,000 UTF-8 bytes in one article, and more than 200,000 characters
+  or 800,000 UTF-8 bytes across a batch. Use the package's compact or Arrow API for
+  large datasets. Batch rows must have exactly four columns. Publication timestamps
+  are capped at 128 characters, while article IDs and sources are capped at 256
+  characters each. Metadata across the batch is capped at 64,000 characters and
+  256,000 UTF-8 bytes, and combined article and metadata cell content is capped at
+  264,000 characters and 1,056,000 UTF-8 bytes. These caps do not count JSON framing
+  or Gradio's transport envelope. A separate 4 MiB server limit covers the complete
+  HTTP request body before JSON parsing.
+- Downloaded evidence identifies the screened article by text length and SHA-256 hash
+  instead of copying the screened text. RANGE removes leading and trailing whitespace
+  before screening. Download files become eligible for best-effort
+  deletion after five minutes, cleanup runs once a minute, and a Space restart may
+  remove them sooner. They are not durable or private storage.
+- Production responses hide internal error details. Use the Space logs to diagnose a
+  failure; do not expose a traceback or exception text in the browser.
+- Package benchmark rates describe the native batch engine on the recorded hardware,
+  not the latency or throughput of this shared two-core hosted demo.
+- A `relevant` result means the configured financial and economic policy accepted the
+  article. It is not sentiment, materiality, a return forecast, or investment advice.
+
+## Planned Python 3.12 migration
+
+The current alpha bundle uses CPython 3.10. Python 3.12 support is a planned follow-up,
+not part of this deployment. Because RANGE includes a compiled Rust extension, that
+migration must update and test the package metadata, build image, native wheel, Space
+runtime, exported bundle, and clean-install checks together. Do not change only the
+Space metadata or try to load the existing `cp310` wheel in Python 3.12.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Ferrell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PACKAGE_README.md

@@ -0,0 +1,350 @@
+# RANGE
+
+**Rapid Analysis of News for the General Economy**
+
+RANGE screens timestamped financial news for economic and broad-market relevance
+at high throughput while preserving the evidence trail behind every result.
+
+The Python distribution is `range-news` and the import namespace is `range_news`.
+
+![Status](https://img.shields.io/badge/status-research%20alpha-orange)
+![Python](https://img.shields.io/badge/python-3.10-blue)
+![Engine](https://img.shields.io/badge/engine-Rust-dea584)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+RANGE answers three practical questions for each article:
+
+1. **Does the article pass the configured financial and economic relevance screen?**
+2. **Which configured broad-market exposures does that evidence reach?**
+3. **What exact text, rule, identity, and relationship produced the result?**
+
+It runs on CPU, makes no network request during inference, and does not depend on an embedding model, an external API, or an LLM. The `0.1.0a1` source and CI artifacts are prepared for review but are **not published to PyPI**.
+
+## See it in 30 seconds
+
+Install from this checkout:
+
+```bash
+cd dataset/news_relevance/range_news
+python -m pip install .
+```
+
+Then screen one article:
+
+```python
+from range_news import RelevanceEngine
+
+engine = RelevanceEngine(workers=1)
+
+decision = engine.predict(
+    (
+        "CPI inflation cooled after the Federal Reserve cut the federal funds rate. "
+        "The S&P 500 and Nasdaq-100 advanced."
+    ),
+    timestamp="2025-01-15T10:30:00-05:00",
+    article_id="economy-example",
+    source="example",
+)
+
+print("status:", decision.status)
+print("accepted:", decision.accepted)
+print("markets:", ", ".join(decision.relevant_to))
+```
+
+Output:
+
+```text
+status: relevant
+accepted: True
+markets: S&P 500, Nasdaq-100, Broad market
+```
+
+The concise summary is JSON-ready:
+
+```python
+print(decision.summary())
+```
+
+The full explanation is generated from the evidence already recorded — inference is not run twice:
+
+```python
+print(engine.explain(decision, detail="audit"))
+```
+
+[`examples/quickstart.py`](examples/quickstart.py) is the executable version checked by CI.
+
+## Why use RANGE?
+
+| Need | What RANGE provides |
+| --- | --- |
+| Filter large news collections | Compact list and Arrow paths return only rows with findings. |
+| Explain every result | Literal spans, offsets, rules, catalog IDs, context checks, and relationship lineage. |
+| Reproduce a screen later | Timestamp-aware identities plus a deterministic taxonomy fingerprint. |
+| Keep data local | CPU execution with no inference-time network call. |
+| Separate relevance from prediction | No sentiment score, return forecast, or trade recommendation is invented. |
+
+Typical users include quantitative researchers, financial-data engineers, news-intelligence teams, risk and surveillance analysts, and anyone building a traceable first-stage filter before a more expensive model or human review.
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Timestamped article] --> B[Exact normalization]
+    B --> C[Compiled phrase and identifier matching]
+    C --> D[Context and effective-date checks]
+    D --> E[Identity and relationship resolution]
+    E --> F[Article relevance result]
+    E --> G[Exposure results]
+    F --> H[Exact matched text and rule path]
+    G --> H
+```
+
+The default taxonomy is deliberately general rather than tied to a portfolio. It covers monetary policy, inflation, employment, growth, rates, credit, fiscal policy, trade, disruptions, financial stability, regulation, sectors, company events, and broad U.S. benchmarks. Application-specific security or portfolio mappings can be added downstream without changing the meaning of the core taxonomy.
+
+## Why it is fast
+
+RANGE was optimized as a screening engine rather than a general language model:
+
+- **Compiled multi-pattern matching.** Rust Aho-Corasick automata replace Python loops over individual phrases and identifiers.
+- **Parallel CPU execution.** Rayon distributes independent articles across a bounded worker pool.
+- **Reused worker memory.** Per-worker scratch buffers are cleared and reused instead of being rebuilt for every article.
+- **A fast common path.** Wholly ASCII rows use a specialized normalization path; frozen Unicode lookup tables preserve the exact fallback behavior for other text.
+- **Sparse results.** Compact screening returns only rows that differ from the canonical no-match result.
+- **Arrow-native input.** `screen_arrow()` avoids constructing one Python object for every input row and keeps conversion back to Python outside the hot path.
+
+The result is low-overhead, predictable CPU screening with a rich Python path available whenever full evidence objects are needed.
+
+### Research benchmark context
+
+In our fastest recorded CPU test, RANGE screened **457,735 articles/second in a 500,000-article run** and **395,017 articles/second in a 10,000,000-article run**. We measured this with a specially optimized RANGE build on one Intel i7-10750H Windows laptop using 10 CPU workers. These are the fastest recorded results for the screening step alone. They do not include file loading or the rest of a data pipeline, and performance varies with hardware, article length, and screening rules.
+
+## Choose the right API
+
+| API | Best for | Result shape |
+| --- | --- | --- |
+| `predict()` | One article that needs a complete explanation | Rich immutable decision |
+| `predict_batch()` | A smaller batch where every row needs rich evidence | Tuple of rich decisions |
+| `screen_batch()` | High-throughput Python sequences | Sparse compact batch |
+| `screen_arrow()` | Columnar datasets and large pipelines | Sparse Arrow facts |
+| `rank()` | Deterministic prioritization within an exposure and time bucket | Ranked rich decisions |
+
+## What a rich decision retains
+
+A `predict()` result contains:
+
+- article ID, source, immutable text, and interpreted timestamp;
+- every literal matched span and its source offsets;
+- detection method, rule ID, catalog entry, and catalog version;
+- context acceptance or collision rejection;
+- effective-dated identity resolutions;
+- relationship lineage from an entity to an exposure;
+- accepted, unresolved, and rejected evidence paths; and
+- article-level and exposure-level decisions.
+
+The compact summary stays small:
+
+```python
+prediction = engine.predict(
+    "Initial jobless claims rose as Treasury yields fell.",
+    timestamp="2025-01-16T08:30:00-05:00",
+    article_id="macro-2",
+)
+
+print(prediction.summary())
+print(prediction.why)
+```
+
+Use Mermaid when a visual evidence flow is more useful:
+
+```python
+mermaid_source = engine.explain(prediction, format="mermaid", detail="audit")
+```
+
+## Batch screening
+
+Use the compact path when most rows are expected to have no configured finding:
+
+```python
+screened = engine.screen_batch(
+    [
+        "Ordinary local weather with no financial terms.",
+        "The unemployment rate rose while retail sales weakened.",
+    ],
+    timestamps=[
+        "2025-01-15T10:00:00-05:00",
+        "2025-01-15T10:01:00-05:00",
+    ],
+    article_ids=["local-1", "economy-1"],
+)
+
+print("rows:", screened.count)
+print("rows with findings:", screened.exception_count)
+print("implicit no-match rows:", screened.implicit_zero_count)
+```
+
+```text
+rows: 2
+rows with findings: 1
+implicit no-match rows: 1
+```
+
+Here, an “exception” means a row that differs from the canonical no-match result; it is not a processing error.
+
+## Arrow screening
+
+Install the Arrow extra:
+
+```bash
+python -m pip install ".[arrow]"
+```
+
+Then screen columnar data without materializing one Python input object per row:
+
+```python
+from datetime import datetime, timezone
+
+import pyarrow as pa
+from range_news import RelevanceEngine
+
+batch = pa.record_batch(
+    [
+        pa.array([
+            "Ordinary local weather.",
+            "The Federal Reserve announced a rate cut.",
+        ]),
+        pa.array(
+            [
+                datetime(2025, 1, 15, 15, 0, tzinfo=timezone.utc),
+                datetime(2025, 1, 15, 15, 1, tzinfo=timezone.utc),
+            ],
+            type=pa.timestamp("us", tz="UTC"),
+        ),
+    ],
+    names=["text", "timestamp"],
+)
+
+facts = RelevanceEngine().screen_arrow(batch)
+print("rows:", facts.row_count)
+print("rows with findings:", facts.exception_count)
+sparse_record_batch = facts.to_pyarrow()
+```
+
+## Default taxonomy
+
+| Area | Representative evidence |
+| --- | --- |
+| Monetary policy | central-bank decisions, policy rates, quantitative easing or tightening |
+| Inflation | CPI, PCE, PPI, inflation expectations |
+| Labor markets | payrolls, unemployment, claims, openings, participation, wages |
+| Growth and demand | GDP, retail sales, production, surveys, confidence, housing, orders |
+| Financial conditions | Treasury yields, yield curve, credit spreads, lending standards, dollar |
+| Fiscal and trade policy | deficits, debt limit, shutdowns, tariffs, export controls |
+| Disruptions and stability | supply chains, banking stress, systemic risk, sanctions, volatility |
+| Regulation | broad securities rulemaking and banking-capital policy |
+| Financial context | sectors and company events accepted at article level without implying a broad exposure |
+| Broad benchmarks | S&P 500, Nasdaq-100, Russell 2000, plus SPY, QQQ, and IWM aliases |
+
+General economic rules may support `Broad market`. Explicit benchmark evidence may support its configured broad exposure. Company-event or sector evidence can be accepted as financial context without being converted into an unsupported security-level or broad-market exposure; article relevance and supported exposure remain separate outputs.
+
+## Customize the taxonomy
+
+Copy the bundled configuration and catalogs to editable YAML:
+
+```python
+from range_news import copy_default_taxonomy
+
+config_path = copy_default_taxonomy("my_taxonomy")
+print(config_path)
+```
+
+Or add an application-owned rule in Python:
+
+```python
+from range_news import DefaultTaxonomy, RelevanceEngine
+
+
+def add_regional_indicator(builder):
+    builder.add_lexical_rule(
+        rule_id="regional-manufacturing-survey",
+        entity_concept="macroeconomic_indicator",
+        tag_type="macroeconomic",
+        phrases=("regional manufacturing survey",),
+        market_wide_authorized=True,
+        source_id="my-research-project",
+    )
+
+
+taxonomy = DefaultTaxonomy().extend(add_regional_indicator)
+custom_engine = RelevanceEngine(taxonomy=taxonomy)
+print(custom_engine.taxonomy.fingerprint)
+```
+
+Each changed taxonomy receives a new deterministic fingerprint. See [the taxonomy guide](docs/taxonomy.md) for the complete extension model.
+
+## Space-ready demo
+
+A polished Gradio demonstration is staged in [`app/`](README.md). It includes:
+
+- single-article analysis with highlighted evidence;
+- a structured evidence table and evidence JSON;
+- Mermaid evidence-flow source for developer-owned rendering;
+- a capped batch-screening tab with downloadable JSONL;
+- named Gradio API endpoints for people and agents; and
+- two supported deployment routes from the same app: local Docker and a free private
+  Gradio/ZeroGPU-compatible Space whose predictions still run on CPU.
+
+The hosted demo applies the same size limits to browser and direct API requests.
+Generated evidence downloads omit the screened article text, retain its length and
+SHA-256 hash, and become eligible for best-effort deletion after five minutes. See the
+deployment guide before making a Space public: public visibility exposes the app,
+bundled package source and native runtime, documentation, and default taxonomy.
+
+Run it locally:
+
+```bash
+python -m pip install ".[demo]"
+python app/app.py
+```
+
+Validate and export a standalone Space bundle without uploading anything:
+
+```bash
+python app/validate_space.py
+python app/export_space.py --target docker --output build/huggingface-space --force
+```
+
+See [`app/DEPLOYMENT.md`](DEPLOYMENT.md) for the local Docker workflow and the
+complete free private Hugging Face workflow, including its portable Linux wheel.
+
+## Scope and limitations
+
+RANGE is a traceable screening layer, not an open-ended semantic model. It intentionally does **not**:
+
+- infer sentiment, causality, magnitude, or expected return;
+- recommend a trade or decide whether news is bullish or bearish;
+- fuzzy-correct misspellings or paraphrases outside the configured taxonomy;
+- provide a complete security master or constituent history;
+- update its taxonomy automatically; or
+- guarantee that every economically important article contains a configured phrase.
+
+Unmapped but plausible evidence should remain reviewable or be handled by an explicit custom taxonomy rather than silently becoming a security-level claim.
+
+## Package status
+
+- Distribution: `range-news`
+- Import: `range_news`
+- Version: `0.1.0a1`
+- Runtime: CPython 3.10
+- Shipping backend: CPU/Rust
+- License: MIT
+- Publication: disabled in this pull request
+
+A coordinated move to CPython 3.12 is planned after this alpha. Because the backend is
+a native extension, the package metadata, build images, wheel, hosted runtime, and
+clean-install tests must migrate together.
+
+The dedicated package workflow builds and checks wheel and source artifacts on Windows and Linux, installs both into clean environments, runs the public contracts and README example outside the repository, verifies taxonomy and Unicode assets, validates the Space scaffold, and retains review artifacts. It contains no package-index credential or publication step.
+
+See [the release-candidate contract](docs/release.md), [technical sign-off](docs/technical-signoff.md), and [changelog](CHANGELOG.md).
+
+This software is for research and information-screening workflows. It does not provide investment advice.

README.md

@@ -0,0 +1,154 @@
+---
+title: RANGE
+emoji: 🔎
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: "6.26.0"
+app_file: app.py
+python_version: "3.10.13"
+pinned: false
+license: mit
+suggested_hardware: zero-a10g
+short_description: Fast, explainable financial-news screening.
+tags:
+- financial-analysis
+- text-analysis
+- information-extraction
+- explainable-ai
+- rust
+---
+
+# RANGE
+
+**Rapid Analysis of News for the General Economy**
+
+RANGE checks timestamped financial news, identifies whether it matches the current
+financial and economic rules, shows any supported broad-market connection, and
+explains exactly which words and rules produced the result.
+
+The article screen and exposure map are separate results. A company event, for example,
+can be accepted as financial context without supporting a bundled broad-market
+exposure.
+
+The engine runs inside this Space with no LLM, model download, API key, or outbound
+inference service. In a hosted Space, submitted text is still processed on Hugging Face
+infrastructure; do not submit material you are not permitted to share.
+
+The repository can produce a local Docker bundle or a free Gradio/ZeroGPU-compatible
+bundle. Both execute the same compiled CPU/Rust predictor; ZeroGPU is a hosting route,
+not a RANGE GPU backend or a GPU benchmark.
+
+> **Hosting note:** This free Gradio deployment uses the ZeroGPU runtime, but RANGE's real prediction endpoints stay on CPU and never request a GPU allocation.
+
+## What the demo returns
+
+For one article, the app shows two related outputs:
+
+- **Article relevance:** `relevant` or `not_relevant` in this deterministic demo, with
+  a plain-language result in the interface. The package contract reserves
+  `needs_review` for optional unresolved semantic evidence.
+- **Supported exposure:** Broad market, S&P 500, Nasdaq-100, or Russell 2000 when an
+  accepted evidence path supports one; otherwise none.
+
+It also returns:
+
+- a concise reason suitable for an application;
+- highlighted accepted, review, and rejected matches in the original text;
+- offsets, matching method, rules, identities, and exposure lineage;
+- a downloadable evidence record that identifies the submitted text by its length and
+  SHA-256 hash instead of repeating the full article; and
+- Mermaid source for developer-owned evidence-flow rendering.
+
+A second tab screens a small editable batch and exports JSONL. Requests are capped at
+100 rows, 20,000 characters and 80,000 UTF-8 bytes per article, and 200,000 characters
+and 800,000 UTF-8 bytes per batch. The Python and Arrow APIs are intended for large
+collections. The web interface and its named API endpoints enforce the same limits
+before running the screening engine. Batch rows must have exactly the four displayed
+columns, metadata fields have separate size limits, and nested values are rejected.
+Combined article and metadata cell content cannot exceed 264,000 characters or
+1,056,000 UTF-8 bytes. These figures do not include JSON framing or Gradio's transport
+envelope. A separate 4 MiB server limit covers the complete HTTP request body before
+JSON parsing.
+
+Download files are temporary conveniences, not storage. A generated file becomes
+eligible for deletion after five minutes, and the app makes a best-effort cleanup pass
+once a minute. The host may remove it sooner when the Space restarts. Save a file
+promptly if you need it, and do not rely on the download link as an archive.
+
+## Why it is fast
+
+RANGE is a compiled screening engine rather than an open-ended language model:
+
+- Rust Aho-Corasick automata scan many configured phrases together.
+- Rayon distributes independent articles across CPU workers.
+- Worker-local buffers are reused instead of rebuilt for every row.
+- Common ASCII news text uses a specialized normalization path, while frozen Unicode
+  tables keep fallback behavior deterministic.
+- Compact and Arrow package APIs represent the common no-match case sparsely.
+
+In our fastest recorded CPU test, RANGE screened **457,735 articles/second in a
+500,000-article run** and **395,017 articles/second in a 10,000,000-article run**.
+We measured this with a specially optimized RANGE build on one Intel i7-10750H Windows
+laptop using 10 CPU workers. These are the fastest recorded results for the screening
+step alone. Loading data, running a complete pipeline, and using the hosted demo will
+be slower. Speed varies with hardware, article length, and screening rules.
+
+## What the result means
+
+A `relevant` result means the article passed the configured financial and economic
+relevance policy. Evidence-path state and supported exposure are reported separately.
+Neither result means the article is bullish, bearish, material, complete, or
+predictive of returns.
+
+The app does not perform sentiment analysis, investment recommendations, fuzzy
+semantic search, or LLM inference. Each result remains traceable to literal
+observations and explicit policy.
+
+## API and coding agents
+
+The Gradio functions expose named endpoints:
+
+- `/analyze` — one timestamped article with detailed evidence;
+- `/batch` — up to 100 timestamped articles with JSONL summaries.
+
+After this bundle is deployed to `<namespace>/<space>`, inspect the generated agent
+instructions with:
+
+```bash
+curl -H "Authorization: Bearer $HF_TOKEN" \
+  https://huggingface.co/spaces/<namespace>/<space>/agents.md
+```
+
+That document tells coding agents how to discover and call the Space API. Private
+Spaces require a Hugging Face bearer token for both `agents.md` and API requests. The
+Space does not need a separate model endpoint.
+
+## Package
+
+This app is built from **RANGE 0.1.0a1**, a deterministic CPU/Rust research alpha.
+The Python distribution is `range-news` and the import namespace is `range_news`.
+The standalone bundle includes
+the default taxonomy used by the demo. Package users can copy and edit its YAML or
+extend the taxonomy in Python without modifying the engine.
+
+See `PACKAGE_README.md` in an exported bundle for the full Python API, taxonomy, benchmark context, and limitations.
+
+## Safety and scope
+
+This software is for research and information-screening workflows. It does not provide
+investment advice. A hosted production deployment returns a simple error to the user
+when something unexpected fails; diagnostic details stay in the host logs.
+
+Do not submit private, licensed, or confidential article text to a public deployment
+unless you have permission to do so. The article text is still processed on the Space host
+and can appear in the interactive page even though downloaded evidence records omit it.
+
+Making the Space public also makes its repository public. That includes the app source,
+bundled RANGE source and native runtime, package documentation, and default taxonomy.
+Keep credentials, private datasets, licensed articles, local paths, and unpublished
+rules out of every uploaded file and revision.
+
+The current alpha uses CPython 3.10. Moving the native package and Space runtime to
+CPython 3.12 is planned as a separate, tested migration; the existing CPython 3.10
+wheel cannot be reused for that change.

SPACE_BUNDLE_MANIFEST.json

@@ -0,0 +1,79 @@
+{
+  "files": {
+    ".gitattributes": "30af955bc8b9589ff13954efae1020fb4fcbd3e2114ce2530c1e19a198331490",
+    "CHANGELOG.md": "04441fe7ba8cc83498bf014cda1b29bcb6f7c148cfbbe3452dc7a9dea9af85ef",
+    "CITATION.cff": "acf3bf2c922c2afd0f8cc336024f525d9334c4b94b83efaa96dc36a1df5c6198",
+    "Cargo.lock": "64eaf82038b21074bf9d6b30e00bf05536958b08463dbe4a4c9a88a86e28a2d8",
+    "Cargo.toml": "f58a8af353ccba4309f9ddddc3e138634093ab2545bfef5214b6a08815d37d59",
+    "DEPLOYMENT.md": "2d005b4059d06bc5e722d67acfe33b97a1b631ac9537e69721e0920b26ba2c0d",
+    "LICENSE": "98564786fde1cf443f2b761bc9c3b329dcac3528b3c383a66b25101ee9670585",
+    "PACKAGE_README.md": "e6fe56bcb6c0cf24a6c7b3859527ab043c341a7c40b5eb3f919a9bccab33382c",
+    "README.md": "423104b0ef72e4e605c4facf10681f0741d43eb8a70ea6932fc945e84d474048",
+    "app.py": "138adcabfb167a19a499d3c0f80bfa63b565c61c3fac1e1d31c04f12bcc5e622",
+    "docs/attention2alpha-compatibility-review.md": "c6e28e67b5528c5683efa6cb98603a9f46e42430c96bee6da4a3a5af9bf94c13",
+    "docs/performance.md": "9d4c99009993527e49f2ce3bb38d3156f1b7e1425723f0093c7873c544261b24",
+    "docs/readme-research.md": "f69255682495de999875c91a8c4dee2e59e1b185877920cf4c85f0ccd49053f3",
+    "docs/release.md": "ce56bb5c7f456a710c90bed63ce2dfe90632d1b0208cc16d06e0b37ad0470bbe",
+    "docs/taxonomy.md": "899b86c816ead8cd9bae9b58f96d0d21a1439cc778e6b61e7c17644a64dc1abf",
+    "docs/technical-signoff.md": "4c1efa828b2460ff5092f07df30319ca7775ec3118ccdfc573aaa5b2980928c5",
+    "examples.py": "94da2be9d8e523a54b6aae6fbd365c5e3456e836b120e4a4a0bd78acb5969d10",
+    "examples/app.py": "53c76cc3834e73435483db6fbf89d8125a0f7aa590269d880cffdaa8e40097f5",
+    "examples/benchmark_hf.py": "5df4e9d756a6447eb5f462ac7b72aaf2a8c1d92558a58620e5abb51e97e62bca",
+    "examples/custom_taxonomy.py": "9c98ed10f258a4503faa783068676f027328a2944b22493de49592057be3aa5d",
+    "examples/quickstart.py": "19bdd779ec202957c72c2b49e7bf778a13ea1b94d0a52f1bba5521810eb71626",
+    "pyproject.toml": "d40182524a367d9ad2d08892450b4bcecfb2133c92bf45867c4e8f4a05910300",
+    "requirements.txt": "94f5ee00edc14a89e5bf6f5fcb90261cde4a57dc3ebc20e0639e68ec504cc220",
+    "rust/core.rs": "9ec890063a3485ab90f9f517a0e8c17b4ba52d66d937f2b9f6cf521889590f1a",
+    "rust/generated/python_whitespace.bin": "6c314375b6c075589b515139e50068d72c0cbd7daf4246e555a9dcfc9748ecc9",
+    "rust/generated/unicode_index.bin": "fe152ac184aa77c40d0f040ba725140b17d845bae9fae255b2b3d3c43bb79c8f",
+    "rust/generated/unicode_meta.txt": "d7b7f5d807b712597a04e8cf1394c1734962c4e042057cc7fca85f5173919d38",
+    "rust/generated/unicode_pool.bin": "109a8da1563408ad1da82919a5dfa1ab9fa18870f0f4d22e2818857b5a4fc30f",
+    "rust/lib.rs": "f6a2205062c2272b13b925deb1883ff1fab10aa5e40a46695bfe96a5626b5753",
+    "src/range_news/__init__.py": "816ba0ee72545cc03d6e5183d46530acd026e67f4b38d6d972a1abd520eb899d",
+    "src/range_news/_core/__init__.py": "7e6c8615e347bca422f9b1e6e10160ac277c346956adf9e86a8a08419f879e96",
+    "src/range_news/_core/accelerated/__init__.py": "ed04df1ca0da8254d9558201c6172969626aced74864842c5a17068ce87a6999",
+    "src/range_news/_core/accelerated/compact.py": "97730675a2563d4e196c06c826e2e2099ff0d123ee027bd0b2888b2aba75825b",
+    "src/range_news/_core/accelerated/indicator.py": "e2ce4da9561752b1f3622b140fd7d798aaf7dd0eebc4828b928f80454de1c740",
+    "src/range_news/_core/catalogs.py": "324f63cb5c0653c11dd7ca626d17f919b06c148794b9988e52890816289ba66f",
+    "src/range_news/_core/catalogs/entities.yml": "5849fe67d3e642ed9a6f67b5f8e0ed83fd850bb570b8ea4cf8ba0cf13bc24548",
+    "src/range_news/_core/catalogs/lexical.yml": "d58e2b64b4f9fe3aba4b0bbc671b05eaeb343955255014cf2577d41935abc14a",
+    "src/range_news/_core/config.py": "6599b43888463e67255d588ab50f408a077a2a6e52361503b85b711b61b678b0",
+    "src/range_news/_core/configs/default.yml": "6e443b14b9e7c4524e8dbdd3035726627345d01d02cc21de7a53a133dea5802c",
+    "src/range_news/_core/indicator.py": "488178693d90e7a7f329b40309eb4583908d5a990cd0b293b272c5fbb192f3a4",
+    "src/range_news/_core/models.py": "e152077ecd18c31eed76b150e234934180a5ffad061d2bf26e35229160cf2733",
+    "src/range_news/_taxonomy_impl.py": "db6802ef00114e33bbb47b2d71886f037e151f397ae82258d1a6760f43bdfed1",
+    "src/range_news/api.py": "1d165a3211fad9a9de1c274320dc21e787303fcd1a37599e399ba82881d4886d",
+    "src/range_news/backends.py": "7a25879d21ed9992aeecc9dc5f4093de00ae68c117646b132140d663987829ca",
+    "src/range_news/customization.py": "6f5e4ae6ba6576cd0fb6a84cb1cfbe85b6da973ab6a411a9d2fdd243ef906355",
+    "src/range_news/models.py": "305c227238efa18be762fbcad7bdd6ee3fee1274d1e4c866854589319191ac24",
+    "src/range_news/py.typed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "vendor/range_news/__init__.py": "816ba0ee72545cc03d6e5183d46530acd026e67f4b38d6d972a1abd520eb899d",
+    "vendor/range_news/_core/__init__.py": "7e6c8615e347bca422f9b1e6e10160ac277c346956adf9e86a8a08419f879e96",
+    "vendor/range_news/_core/accelerated/__init__.py": "ed04df1ca0da8254d9558201c6172969626aced74864842c5a17068ce87a6999",
+    "vendor/range_news/_core/accelerated/compact.py": "97730675a2563d4e196c06c826e2e2099ff0d123ee027bd0b2888b2aba75825b",
+    "vendor/range_news/_core/accelerated/indicator.py": "e2ce4da9561752b1f3622b140fd7d798aaf7dd0eebc4828b928f80454de1c740",
+    "vendor/range_news/_core/catalogs.py": "324f63cb5c0653c11dd7ca626d17f919b06c148794b9988e52890816289ba66f",
+    "vendor/range_news/_core/catalogs/entities.yml": "5849fe67d3e642ed9a6f67b5f8e0ed83fd850bb570b8ea4cf8ba0cf13bc24548",
+    "vendor/range_news/_core/catalogs/lexical.yml": "d58e2b64b4f9fe3aba4b0bbc671b05eaeb343955255014cf2577d41935abc14a",
+    "vendor/range_news/_core/config.py": "6599b43888463e67255d588ab50f408a077a2a6e52361503b85b711b61b678b0",
+    "vendor/range_news/_core/configs/default.yml": "6e443b14b9e7c4524e8dbdd3035726627345d01d02cc21de7a53a133dea5802c",
+    "vendor/range_news/_core/indicator.py": "488178693d90e7a7f329b40309eb4583908d5a990cd0b293b272c5fbb192f3a4",
+    "vendor/range_news/_core/models.py": "e152077ecd18c31eed76b150e234934180a5ffad061d2bf26e35229160cf2733",
+    "vendor/range_news/_native.cpython-310-x86_64-linux-gnu.so": "45e05c00ab729ead671436ed8bd392c016dfa1e44ef42fdfade758902b1519d1",
+    "vendor/range_news/_taxonomy_impl.py": "db6802ef00114e33bbb47b2d71886f037e151f397ae82258d1a6760f43bdfed1",
+    "vendor/range_news/api.py": "1d165a3211fad9a9de1c274320dc21e787303fcd1a37599e399ba82881d4886d",
+    "vendor/range_news/backends.py": "7a25879d21ed9992aeecc9dc5f4093de00ae68c117646b132140d663987829ca",
+    "vendor/range_news/customization.py": "6f5e4ae6ba6576cd0fb6a84cb1cfbe85b6da973ab6a411a9d2fdd243ef906355",
+    "vendor/range_news/models.py": "305c227238efa18be762fbcad7bdd6ee3fee1274d1e4c866854589319191ac24",
+    "vendor/range_news/py.typed": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  "format": "range-news-hugging-face-space-bundle-v1",
+  "hardware": "zero-a10g",
+  "package": "range-news",
+  "runtime_package": "vendor/range_news",
+  "sdk": "gradio",
+  "source_wheel": "range_news-0.1.0a1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl",
+  "source_wheel_sha256": "c72a0f0d174e028f0a3db338c13e1dbf3e905ff2f67bacc0b3966a2386c2681b",
+  "target": "zerogpu",
+  "version": "0.1.0a1"
+}

app.py

@@ -0,0 +1,1172 @@
+"""Space-ready Gradio demo for explainable financial-news relevance screening."""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import html
+import json
+import os
+import sys
+import uuid
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+from starlette.middleware import Middleware
+from starlette.middleware.body_limit import RequestBodyLimitMiddleware
+from gradio.utils import get_upload_folder
+
+VENDORED_PACKAGE_ROOT = Path(__file__).resolve().parent / "vendor"
+if VENDORED_PACKAGE_ROOT.is_dir():
+    sys.path.insert(0, str(VENDORED_PACKAGE_ROOT))
+
+try:
+    import spaces
+except ModuleNotFoundError:  # Local installs and the Docker image do not need it.
+    spaces = None
+
+from range_news import RelevanceEngine, __version__
+
+from examples import ARTICLE_EXAMPLES, BATCH_ROWS, SINGLE_EXAMPLES
+
+
+if spaces is not None:
+
+    @spaces.GPU(duration=1)
+    def _zerogpu_hosting_marker() -> None:
+        """Register the free ZeroGPU runtime without moving CPU inference to a GPU."""
+
+        return None
+
+
+GRADIO_MAJOR = int(gr.__version__.split(".", 1)[0])
+THEME = gr.themes.Soft(primary_hue="teal", neutral_hue="slate")
+MAX_BATCH_ROWS = 100
+EXPECTED_BATCH_COLUMNS = 4
+MAX_ARTICLE_CHARS = 20_000
+MAX_ARTICLE_BYTES = 80_000
+MAX_TIMESTAMP_CHARS = 128
+MAX_TIMESTAMP_BYTES = 512
+MAX_ARTICLE_ID_CHARS = 256
+MAX_ARTICLE_ID_BYTES = 1_024
+MAX_SOURCE_CHARS = 256
+MAX_SOURCE_BYTES = 1_024
+MAX_BATCH_CHARS = 200_000
+MAX_BATCH_BYTES = 800_000
+MAX_BATCH_METADATA_CHARS = 64_000
+MAX_BATCH_METADATA_BYTES = 256_000
+MAX_BATCH_CONTENT_CHARS = MAX_BATCH_CHARS + MAX_BATCH_METADATA_CHARS
+MAX_BATCH_CONTENT_BYTES = MAX_BATCH_BYTES + MAX_BATCH_METADATA_BYTES
+MAX_HTTP_REQUEST_BYTES = 4 * 1024 * 1024
+EVIDENCE_HEADERS = [
+    "evidence path",
+    "matched text",
+    "offsets",
+    "type",
+    "method",
+    "rule or catalog",
+    "identity",
+    "exposure",
+]
+BATCH_HEADERS = [
+    "article_id",
+    "status",
+    "accepted",
+    "relevant_to",
+    "why",
+]
+
+CSS = """
+html, body {width: 100%; margin: 0 !important; overflow-x: clip;}
+.gradio-container {
+  width: 100% !important;
+  max-width: none !important;
+  margin: 0 !important;
+  padding: 0 0 2rem !important;
+}
+.hero-host {
+  width: 100vw !important;
+  max-width: none !important;
+  margin-inline: calc(50% - 50vw) !important;
+  padding: 0 !important;
+  border: 0 !important;
+  box-sizing: border-box !important;
+}
+.hero {
+  position: relative;
+  width: 100%;
+  margin: 0;
+  overflow: hidden;
+  box-sizing: border-box;
+  border-block: 1px solid var(--border-color-primary);
+  border-inline: 0;
+  background:
+    radial-gradient(circle at 92% 15%, rgba(13, 148, 136, 0.18), transparent 34%),
+    radial-gradient(circle at 8% 88%, rgba(37, 99, 235, 0.12), transparent 30%),
+    linear-gradient(145deg, var(--background-fill-primary), var(--background-fill-secondary));
+  box-shadow: 0 18px 48px rgba(15, 23, 42, 0.08);
+}
+.hero-inner {
+  width: min(calc(100% - 2rem), 1180px);
+  margin-inline: auto;
+  padding: clamp(2.2rem, 5vw, 4.5rem) clamp(1.25rem, 4vw, 3.2rem);
+  box-sizing: border-box;
+  text-align: center;
+}
+.hero-eyebrow,
+.hero h1,
+.hero-expansion,
+.hero-copy,
+.benchmark-note {
+  width: 100%;
+  text-align: center !important;
+}
+.hero-eyebrow {
+  margin: 0 0 0.8rem;
+  color: #0f766e;
+  font-size: 0.78rem;
+  font-weight: 750;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+.hero h1 {
+  max-width: 960px;
+  margin: 0 auto;
+  font-size: clamp(3.4rem, 10vw, 7rem);
+  line-height: 0.92;
+  letter-spacing: -0.065em;
+}
+.hero-expansion {
+  max-width: 960px;
+  margin: 1rem auto 0;
+  font-size: clamp(1.08rem, 2.5vw, 1.55rem);
+  font-weight: 720;
+  line-height: 1.35;
+}
+.hero-copy {
+  max-width: 900px;
+  margin: 1rem auto 0;
+  font-size: clamp(1rem, 1.5vw, 1.16rem);
+  line-height: 1.65;
+  opacity: 0.88;
+}
+.speed-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.75rem;
+  max-width: 900px;
+  margin: 1.6rem auto 0;
+}
+.speed-stat {
+  padding: 0.9rem 1rem;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+  text-align: center;
+}
+.speed-stat strong {display: block; font-size: clamp(1.2rem, 2.6vw, 1.75rem); line-height: 1.15;}
+.speed-stat span {display: block; margin-top: 0.25rem; font-size: 0.8rem; line-height: 1.35; opacity: 0.72;}
+.benchmark-note {max-width: 900px; margin: 0.75rem auto 0; font-size: 0.86rem; line-height: 1.5; opacity: 0.72;}
+.trust-row {display: flex; justify-content: center; flex-wrap: wrap; gap: 0.55rem; margin-top: 1.25rem;}
+.trust-pill {
+  padding: 0.36rem 0.68rem;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 999px;
+  background: var(--background-fill-primary);
+  font-size: 0.82rem;
+  font-weight: 650;
+}
+.value-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 0.8rem;
+  width: min(calc(100% - 2rem), 1120px);
+  max-width: 1120px;
+  margin: 1.15rem auto 1.35rem;
+}
+.content-shell {
+  width: min(calc(100% - 2rem), 1120px) !important;
+  max-width: 1120px !important;
+  margin-inline: auto !important;
+  align-self: center !important;
+}
+.value-card {
+  padding: 1rem 1.05rem;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+  text-align: center;
+}
+.value-card strong {display: block; margin-bottom: 0.25rem; font-size: 0.95rem;}
+.value-card span {font-size: 0.88rem; line-height: 1.45; opacity: 0.78;}
+.status-card {
+  min-height: 255px;
+  padding: 1.15rem 1.25rem;
+  border: 1px solid var(--border-color-primary);
+  border-top: 5px solid #94a3b8;
+  border-radius: 16px;
+  background: var(--background-fill-primary);
+  box-shadow: 0 10px 26px rgba(15, 23, 42, 0.06);
+}
+.status-card.status-relevant {border-top-color: #0f766e;}
+.status-card.status-review {border-top-color: #d97706;}
+.status-card.status-no-match {border-top-color: #64748b;}
+.status-card h3 {margin: 0.5rem 0 0.45rem; font-size: 1.32rem; line-height: 1.25;}
+.status-label {font-size: 0.73rem; font-weight: 750; letter-spacing: 0.1em; opacity: 0.68; text-transform: uppercase;}
+.status-badge {
+  display: inline-block;
+  margin-left: 0.45rem;
+  padding: 0.2rem 0.48rem;
+  border-radius: 999px;
+  background: var(--background-fill-secondary);
+  font-size: 0.72rem;
+  font-weight: 750;
+  letter-spacing: 0.04em;
+}
+.result-grid {display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 0.75rem; margin: 0.9rem 0;}
+.result-cell {padding: 0.72rem 0.8rem; border-radius: 11px; background: var(--background-fill-secondary);}
+.result-cell strong {display: block; margin-bottom: 0.18rem; font-size: 0.78rem; opacity: 0.72;}
+.result-cell span {font-weight: 650; line-height: 1.4;}
+.boundary-note {margin: 0.75rem 0 0; font-size: 0.86rem; line-height: 1.45; opacity: 0.76;}
+.small-note {font-size: 0.78rem; opacity: 0.64;}
+.evidence-legend {display: flex; flex-wrap: wrap; gap: 0.55rem 1rem; margin: 0 0 0.65rem; font-size: 0.83rem;}
+.legend-key {display: inline-flex; align-items: center; gap: 0.35rem;}
+.legend-swatch {width: 0.72rem; height: 0.72rem; border-radius: 3px; border: 1px solid rgba(15, 23, 42, 0.16);}
+.swatch-accepted {background: #99f6e4;}
+.swatch-review {background: #fde68a;}
+.swatch-rejected {background: #e2e8f0;}
+.swatch-observed {background: #bfdbfe;}
+mark.evidence {padding: 0.08rem 0.2rem; border-radius: 0.25rem; color: #111827;}
+mark.evidence:focus {outline: 2px solid #2563eb; outline-offset: 2px;}
+mark.evidence-accepted {background: #99f6e4;}
+mark.evidence-review {background: #fde68a;}
+mark.evidence-rejected {background: #e2e8f0; text-decoration: line-through; text-decoration-thickness: 1px;}
+mark.evidence-observed {background: #bfdbfe;}
+.article-preview {
+  min-height: 5.5rem;
+  line-height: 1.8;
+  white-space: pre-wrap;
+  padding: 1rem 1.05rem;
+  border: 1px solid var(--border-color-primary);
+  border-radius: 14px;
+  background: var(--background-fill-primary);
+}
+.empty-preview {opacity: 0.68;}
+.privacy-note {
+  margin-top: 1rem;
+  padding: 0.85rem 1rem;
+  border-left: 4px solid #64748b;
+  border-radius: 8px;
+  background: var(--background-fill-secondary);
+  font-size: 0.88rem;
+  line-height: 1.5;
+}
+@media (max-width: 760px) {
+  .speed-grid, .value-grid, .result-grid {grid-template-columns: 1fr;}
+  .hero-inner {padding: 1.8rem 1.25rem 2rem;}
+  .speed-stat {text-align: center;}
+  .status-card {min-height: auto;}
+}
+"""
+
+ABOUT = """
+## What RANGE does
+
+RANGE is a **deterministic screening layer** for timestamped economic and financial
+news. It answers two related questions separately:
+
+1. Did the article pass the configured financial and economic relevance screen?
+2. Did that evidence support a configured broad-market exposure?
+
+It also preserves the exact text, offsets, rules, time-valid identities, and
+relationships behind the result. The screening logic is deterministic and versioned.
+
+### From article to result
+
+```text
+article + publication time
+  → literal phrase and identifier matches
+  → context, identity, and effective-date checks
+  → accepted / review / rejected evidence paths
+  → article relevance + supported broad-market exposure
+```
+
+### Why it is fast
+
+- **Compile once, scan together.** Rust Aho-Corasick automata check many configured
+  phrases in one pass instead of running a Python loop for every rule.
+- **Use the CPU cores.** Rayon processes independent articles in parallel.
+- **Avoid repeated allocation.** Worker-local scratch buffers are reused across rows.
+- **Optimize common news text.** ASCII input takes a specialized path while frozen
+  Unicode tables preserve deterministic fallback behavior.
+- **Keep empty results cheap.** Compact list and Arrow interfaces return sparse facts
+  rather than building a rich Python object for every no-match row.
+
+In our fastest recorded CPU test, RANGE screened **457,735 articles/second in a
+500,000-article run** and **395,017 articles/second in a 10,000,000-article run**.
+We measured this with a specially optimized RANGE build on one Intel i7-10750H Windows
+laptop using 10 CPU workers. These are the fastest recorded results for the screening
+step alone. Loading data, running a complete pipeline, and using the hosted demo will
+be slower. Speed varies with hardware, article length, and screening rules.
+
+### What it is not
+
+This demo does not infer sentiment, forecast returns, recommend a position, or use an
+LLM. A `relevant` result means the article passed the bundled financial and economic
+relevance policy; evidence-path state and supported exposure are reported separately.
+Neither result means the news is bullish, bearish, material, complete, or predictive
+of returns.
+
+The hosted demo is intended for short evaluation inputs. The downloadable package APIs
+are the appropriate interface for large datasets.
+"""
+
+HERO_HTML = """
+<section class="hero">
+  <div class="hero-inner">
+    <p class="hero-eyebrow">Fast · consistent · shows its work</p>
+    <h1>RANGE</h1>
+    <p class="hero-expansion">Rapid Analysis of News for the General Economy</p>
+    <p class="hero-copy">
+      RANGE quickly checks financial news for economic and broad-market relevance.
+      It tells you whether an article matches, which broad market or index it relates to, and
+      the exact words and rule behind the result—without using an LLM or sending the
+      article to an external API.
+    </p>
+    <div class="speed-grid" aria-label="Recorded CPU benchmark highlights">
+      <div class="speed-stat"><strong>457,735</strong><span>articles screened per second in a 500,000-article test</span></div>
+      <div class="speed-stat"><strong>395,017</strong><span>articles screened per second in a 10-million-article test</span></div>
+      <div class="speed-stat"><strong>Clear reasons</strong><span>Every result includes the matched words and rule</span></div>
+    </div>
+    <p class="benchmark-note">Measured with a specially optimized RANGE build on one Intel i7-10750H Windows laptop using 10 CPU workers. These are the fastest recorded results for the screening step alone. Loading data, running a complete pipeline, and using the hosted demo will be slower. Speed varies with hardware, article length, and screening rules.</p>
+    <div class="trust-row" aria-label="Product characteristics">
+      <span class="trust-pill">Rust-accelerated on CPU</span>
+      <span class="trust-pill">Screening rules you can customize</span>
+      <span class="trust-pill">Exact matched text and rules</span>
+    </div>
+  </div>
+</section>
+<section class="value-grid" aria-label="What RANGE returns">
+  <div class="value-card"><strong>Article relevance</strong><span>Whether the article matches the financial and economic topics in the current rules.</span></div>
+  <div class="value-card"><strong>Related market</strong><span>Broad market, S&amp;P 500, Nasdaq-100, or Russell 2000—when the article supports the connection.</span></div>
+  <div class="value-card"><strong>Evidence trail</strong><span>Matched words → rule → name valid on the publication date → market connection.</span></div>
+</section>
+"""
+
+INITIAL_STATUS_HTML = """
+<div class="status-card status-empty" role="status" aria-live="polite">
+  <span class="status-label">Screening result</span>
+  <h3>Your result will appear here</h3>
+  <p>RANGE reports article relevance and supported broad-market exposure as two
+  separate outputs.</p>
+  <div class="result-grid">
+    <div class="result-cell"><strong>Article relevance</strong><span>Relevant · No configured match</span></div>
+    <div class="result-cell"><strong>Related market</strong><span>Shown only when the article supports a connection</span></div>
+  </div>
+  <p class="boundary-note">This is a relevance screen—not sentiment, materiality, a
+  return forecast, or investment advice.</p>
+</div>
+"""
+
+
+def _text_size(value: str, *, label: str) -> tuple[int, int]:
+    """Return character and UTF-8 sizes with a public-safe Unicode error."""
+
+    characters = len(value)
+    try:
+        utf8_bytes = len(value.encode("utf-8"))
+    except UnicodeEncodeError as exc:
+        raise gr.Error(f"{label} contains invalid Unicode text.") from exc
+    return characters, utf8_bytes
+
+
+def _validate_article_size(text: str, *, label: str = "Article") -> tuple[int, int]:
+    """Validate public-request bounds before the engine sees article text."""
+
+    characters, utf8_bytes = _text_size(text, label=label)
+    if characters > MAX_ARTICLE_CHARS:
+        raise gr.Error(f"{label} exceeds the {MAX_ARTICLE_CHARS:,}-character limit.")
+    if utf8_bytes > MAX_ARTICLE_BYTES:
+        raise gr.Error(f"{label} exceeds the {MAX_ARTICLE_BYTES:,}-byte UTF-8 limit.")
+    return characters, utf8_bytes
+
+
+def _bounded_metadata(
+    value: Any,
+    *,
+    label: str,
+    max_characters: int,
+    max_bytes: int,
+    required: bool = False,
+) -> tuple[str, int, int]:
+    """Normalize one metadata value after enforcing its raw request bounds."""
+
+    if value is None:
+        raw_value = ""
+    elif isinstance(value, str):
+        raw_value = value
+    else:
+        raise gr.Error(f"{label} must be text.")
+
+    characters, utf8_bytes = _text_size(raw_value, label=label)
+    if characters > max_characters:
+        raise gr.Error(f"{label} exceeds the {max_characters:,}-character limit.")
+    if utf8_bytes > max_bytes:
+        raise gr.Error(f"{label} exceeds the {max_bytes:,}-byte UTF-8 limit.")
+
+    cleaned = raw_value.strip()
+    if required and not cleaned:
+        raise gr.Error(f"Enter {label.lower()}.")
+    return cleaned, characters, utf8_bytes
+
+
+def _batch_cell_text(value: Any, *, label: str) -> str:
+    """Accept ordinary table scalars without stringifying nested objects."""
+
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (bool, int, float)):
+        return str(value)
+    raise gr.Error(f"{label} must be plain text or a number.")
+
+
+def _validate_batch_dimensions(row_count: int, column_count: int) -> None:
+    """Reject oversized or malformed tables before their cells are copied."""
+
+    if row_count > MAX_BATCH_ROWS:
+        raise gr.Error(
+            f"The interactive demo is capped at {MAX_BATCH_ROWS} rows per request."
+        )
+    if column_count != EXPECTED_BATCH_COLUMNS:
+        raise gr.Error(
+            "Batch input must have exactly four columns: "
+            "article_id, timestamp, source, and text."
+        )
+
+
+def _local_error_details_enabled() -> bool:
+    """Allow detailed tracebacks only through an explicit non-Space opt-in."""
+
+    requested = os.environ.get("RANGE_LOCAL_SHOW_ERROR", "").strip().casefold()
+    if requested not in {"1", "true", "yes", "on"}:
+        return False
+    return not any(os.environ.get(name) for name in ("SPACE_ID", "SPACE_HOST"))
+
+
+@lru_cache(maxsize=1)
+def _engine() -> RelevanceEngine:
+    """Create and cache the immutable CPU engine used by this process."""
+
+    return RelevanceEngine()
+
+
+def _jsonable(value: Any) -> Any:
+    """Convert immutable package contracts to ordinary JSON-compatible values."""
+
+    if dataclasses.is_dataclass(value):
+        return {
+            field.name: _jsonable(getattr(value, field.name))
+            for field in dataclasses.fields(value)
+        }
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, Mapping):
+        return {str(_jsonable(key)): _jsonable(item) for key, item in value.items()}
+    if isinstance(value, (tuple, list, set, frozenset)):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, Path):
+        return str(value)
+    attributes = getattr(value, "__dict__", None)
+    if isinstance(attributes, dict):
+        return {
+            str(key): _jsonable(item)
+            for key, item in attributes.items()
+            if not str(key).startswith("_")
+        }
+    return value
+
+
+def _download_file(payload: Any, *, suffix: str) -> str:
+    cache_root = Path(get_upload_folder())
+    cache_root.mkdir(parents=True, exist_ok=True)
+    path = cache_root / f"relevance-{uuid.uuid4().hex}{suffix}"
+    if suffix == ".jsonl":
+        lines = [json.dumps(row, ensure_ascii=False, sort_keys=True) for row in payload]
+        path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    else:
+        path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+    return str(path)
+
+
+def _evidence_sets(prediction) -> tuple[set[str], set[str], set[str]]:
+    accepted = {
+        observation_id
+        for path in prediction.article_decision.accepted_evidence
+        for observation_id in path.observation_ids
+    }
+    unresolved = {
+        observation_id
+        for path in prediction.article_decision.unresolved_evidence
+        for observation_id in path.observation_ids
+    }
+    rejected = {
+        observation_id
+        for path in prediction.article_decision.rejected_evidence
+        for observation_id in path.observation_ids
+    }
+    return accepted, unresolved, rejected
+
+
+def _evidence_rows(prediction) -> list[list[str]]:
+    accepted, unresolved, rejected = _evidence_sets(prediction)
+    resolutions = {
+        resolution.observation_id: resolution for resolution in prediction.resolutions
+    }
+    paths = (
+        *prediction.article_decision.accepted_evidence,
+        *prediction.article_decision.unresolved_evidence,
+        *prediction.article_decision.rejected_evidence,
+    )
+    exposure_by_observation: dict[str, set[str]] = {}
+    for path in paths:
+        label = path.exposure_family.label if path.exposure_family is not None else "—"
+        for observation_id in path.observation_ids:
+            exposure_by_observation.setdefault(observation_id, set()).add(label)
+
+    rows: list[list[str]] = []
+    for observation in prediction.observations:
+        if observation.observation_id in accepted:
+            status = "accepted"
+        elif observation.observation_id in unresolved:
+            status = "unresolved path"
+        elif observation.observation_id in rejected:
+            status = "rejected"
+        else:
+            status = "observed"
+        resolution = resolutions.get(observation.observation_id)
+        identity = (
+            resolution.canonical_id
+            if resolution is not None and resolution.canonical_id
+            else (resolution.status.value if resolution is not None else "—")
+        )
+        lineage = observation.rule_id or observation.catalog_entry_id or "—"
+        rows.append(
+            [
+                status,
+                observation.matched_surface,
+                f"{observation.span_start}:{observation.span_end}",
+                observation.tag_type or observation.entity_concept,
+                observation.detection_method,
+                lineage,
+                identity,
+                ", ".join(
+                    sorted(
+                        exposure_by_observation.get(observation.observation_id, {"—"})
+                    )
+                ),
+            ]
+        )
+    return rows
+
+
+def _highlighted_article(prediction) -> str:
+    text = prediction.article.text
+    accepted, unresolved, rejected = _evidence_sets(prediction)
+
+    def evidence_status(observation_id: str) -> str:
+        if observation_id in accepted:
+            return "accepted"
+        if observation_id in unresolved:
+            return "review"
+        if observation_id in rejected:
+            return "rejected"
+        return "observed"
+
+    status_priority = {"accepted": 0, "review": 1, "rejected": 2, "observed": 3}
+    candidates = sorted(
+        prediction.observations,
+        key=lambda row: (
+            row.span_start,
+            status_priority[evidence_status(row.observation_id)],
+            -(row.span_end - row.span_start),
+            row.observation_id,
+        ),
+    )
+    selected = []
+    cursor = -1
+    for observation in candidates:
+        if observation.span_start < cursor:
+            continue
+        selected.append(observation)
+        cursor = observation.span_end
+
+    pieces: list[str] = []
+    cursor = 0
+    for observation in selected:
+        pieces.append(html.escape(text[cursor : observation.span_start]))
+        status = evidence_status(observation.observation_id)
+        status_label = {
+            "accepted": "Accepted evidence",
+            "review": "Unresolved path",
+            "rejected": "Rejected match",
+            "observed": "Observed match",
+        }[status]
+        title = html.escape(
+            f"{status_label} · {observation.tag_type or observation.entity_concept} · "
+            f"{observation.detection_method} · "
+            f"{observation.span_start}:{observation.span_end}"
+        )
+        surface = html.escape(text[observation.span_start : observation.span_end])
+        aria_label = html.escape(f"{status_label}: {observation.matched_surface}")
+        pieces.append(
+            f'<mark class="evidence evidence-{status}" title="{title}" '
+            f'tabindex="0" aria-label="{aria_label}">{surface}</mark>'
+        )
+        cursor = observation.span_end
+    pieces.append(html.escape(text[cursor:]))
+    legend = (
+        '<div class="evidence-legend" aria-label="Evidence highlight legend">'
+        '<span class="legend-key"><span class="legend-swatch swatch-accepted"></span>Accepted evidence</span>'
+        '<span class="legend-key"><span class="legend-swatch swatch-review"></span>Unresolved path</span>'
+        '<span class="legend-key"><span class="legend-swatch swatch-rejected"></span>Rejected match</span>'
+        '<span class="legend-key"><span class="legend-swatch swatch-observed"></span>Observed match</span>'
+        "</div>"
+    )
+    return legend + '<div class="article-preview">' + "".join(pieces) + "</div>"
+
+
+def _status_card(prediction) -> str:
+    card_class, badge, heading = {
+        "relevant": (
+            "status-relevant",
+            "Relevant",
+            "Article passed the configured relevance screen",
+        ),
+        "needs_review": (
+            "status-review",
+            "Needs review",
+            "Possible evidence needs review",
+        ),
+        "not_relevant": (
+            "status-no-match",
+            "No configured match",
+            "No accepted evidence in the bundled taxonomy",
+        ),
+    }[prediction.status]
+    exposures = ", ".join(prediction.relevant_to)
+    exposure_value = exposures or "None"
+    has_unresolved_path = bool(prediction.article_decision.unresolved_evidence)
+    if exposures:
+        exposure_note = ""
+    elif prediction.status == "relevant" and has_unresolved_path:
+        exposure_note = (
+            '<p class="boundary-note">The article passed at the article level, but '
+            "its highlighted relationship evidence does not complete a configured "
+            "path to a broad-market exposure and is shown as unresolved.</p>"
+        )
+    elif prediction.status == "relevant":
+        exposure_note = (
+            '<p class="boundary-note">The article passed at the article level, but '
+            "no accepted evidence path established one of the bundled broad-market "
+            "exposures.</p>"
+        )
+    else:
+        exposure_note = (
+            '<p class="boundary-note">Article relevance and exposure mapping are '
+            "separate results.</p>"
+        )
+    return (
+        f'<div class="status-card {card_class}" role="status" aria-live="polite">'
+        '<span class="status-label">Screening result</span>'
+        f'<span class="status-badge">{html.escape(badge)}</span>'
+        f"<h3>{html.escape(heading)}</h3>"
+        '<div class="result-grid">'
+        '<div class="result-cell"><strong>Article relevance</strong>'
+        f"<span>{html.escape(badge)}</span></div>"
+        '<div class="result-cell"><strong>Related market</strong>'
+        f"<span>{html.escape(exposure_value)}</span></div>"
+        "</div>"
+        f"<p><strong>Why RANGE returned this:</strong> {html.escape(prediction.why)}</p>"
+        f"{exposure_note}"
+        '<p class="boundary-note">Relevant means the article passed the configured '
+        "screen. It does not mean bullish, bearish, material, or predictive.</p>"
+        f'<p class="small-note">RANGE {html.escape(__version__)} · '
+        f"taxonomy {html.escape(_engine().taxonomy.version)} · "
+        f"CPU workers {_engine().workers}</p>"
+        "</div>"
+    )
+
+
+def _audit_payload(prediction) -> dict[str, Any]:
+    decision = _jsonable(prediction)
+    article = decision.get("article") if isinstance(decision, dict) else None
+    if not isinstance(article, dict):
+        raise RuntimeError("RANGE produced an invalid evidence record.")
+
+    article_text = prediction.article.text
+    encoded_text = article_text.encode("utf-8")
+    article.pop("text", None)
+    article.update(
+        {
+            "text_sha256": hashlib.sha256(encoded_text).hexdigest(),
+            "text_characters": len(article_text),
+            "text_utf8_bytes": len(encoded_text),
+            "text_normalization": "leading_and_trailing_whitespace_removed",
+        }
+    )
+    return {
+        "summary": prediction.summary(),
+        "package_version": __version__,
+        "backend": _jsonable(_engine().backend_info),
+        "taxonomy": _engine().taxonomy.describe(),
+        "decision": decision,
+    }
+
+
+def analyze_article(
+    text: str,
+    timestamp: str,
+    article_id: str,
+    source: str,
+):
+    """Screen one timestamped article for configured financial-news relevance.
+
+    Returns a plain-language result, highlighted evidence, an application-ready
+    summary, rule path, detailed evidence data, Mermaid source, and a download.
+    """
+
+    if not isinstance(text, str):
+        raise gr.Error("Article text must be text.")
+    _validate_article_size(text)
+    cleaned_text = text.strip()
+    if not cleaned_text:
+        raise gr.Error("Enter non-empty article text.")
+    resolved_timestamp, _, _ = _bounded_metadata(
+        timestamp,
+        label="Publication timestamp",
+        max_characters=MAX_TIMESTAMP_CHARS,
+        max_bytes=MAX_TIMESTAMP_BYTES,
+        required=True,
+    )
+    resolved_id, _, _ = _bounded_metadata(
+        article_id,
+        label="Article ID",
+        max_characters=MAX_ARTICLE_ID_CHARS,
+        max_bytes=MAX_ARTICLE_ID_BYTES,
+    )
+    resolved_source, _, _ = _bounded_metadata(
+        source,
+        label="Source",
+        max_characters=MAX_SOURCE_CHARS,
+        max_bytes=MAX_SOURCE_BYTES,
+    )
+
+    try:
+        prediction = _engine().predict(
+            cleaned_text,
+            timestamp=resolved_timestamp,
+            article_id=resolved_id or None,
+            source=resolved_source or "demo",
+        )
+    except (TypeError, ValueError) as exc:
+        raise gr.Error(
+            "The article or publication timestamp is invalid. "
+            "Use an ISO 8601 timestamp such as 2025-01-15T09:30:00-05:00."
+        ) from exc
+
+    audit = _audit_payload(prediction)
+    explanation = _engine().explain(prediction, format="text", detail="audit")
+    diagram = _engine().explain(prediction, format="mermaid", detail="audit")
+    return (
+        _status_card(prediction),
+        _highlighted_article(prediction),
+        prediction.summary(),
+        _evidence_rows(prediction),
+        explanation,
+        json.dumps(audit, ensure_ascii=False, indent=2, sort_keys=True),
+        diagram,
+        _download_file(audit, suffix=".json"),
+    )
+
+
+def _rows(value: Any) -> list[list[Any]]:
+    """Return a small four-column table after validating its shape up front."""
+
+    if value is None:
+        return []
+
+    shape = getattr(value, "shape", None)
+    if shape is not None:
+        try:
+            dimensions = tuple(int(part) for part in shape)
+        except (TypeError, ValueError) as exc:
+            raise gr.Error("Batch input must be a two-dimensional table.") from exc
+        if len(dimensions) != 2:
+            raise gr.Error("Batch input must be a two-dimensional table.")
+        _validate_batch_dimensions(dimensions[0], dimensions[1])
+        if hasattr(value, "values") and hasattr(value.values, "tolist"):
+            converted = value.values.tolist()
+        elif hasattr(value, "tolist"):
+            converted = value.tolist()
+        else:
+            raise gr.Error("Batch input must be a two-dimensional table.")
+        if not isinstance(converted, list):
+            raise gr.Error("Batch input must be a two-dimensional table.")
+        rows: Sequence[Any] = converted
+    else:
+        if not isinstance(value, Sequence) or isinstance(
+            value, (str, bytes, bytearray)
+        ):
+            raise gr.Error("Batch input must be a two-dimensional table.")
+        _validate_batch_dimensions(len(value), EXPECTED_BATCH_COLUMNS)
+        rows = value
+
+    for index, row in enumerate(rows):
+        if not isinstance(row, Sequence) or isinstance(row, (str, bytes, bytearray)):
+            raise gr.Error(f"Batch row {index + 1} must contain four cells.")
+        _validate_batch_dimensions(len(rows), len(row))
+    return [list(row) for row in rows]
+
+
+def analyze_batch(data: Any):
+    """Screen up to 100 timestamped articles and return summaries plus JSONL.
+
+    This hosted-demo endpoint uses the rich prediction path. Use the package's compact
+    or Arrow APIs for high-throughput datasets.
+    """
+
+    normalized: list[tuple[str, str, str, str]] = []
+    total_text_characters = 0
+    total_text_bytes = 0
+    total_metadata_characters = 0
+    total_metadata_bytes = 0
+    for index, row in enumerate(_rows(data)):
+        raw_article_id, raw_timestamp, raw_source, raw_text = (
+            _batch_cell_text(cell, label=f"Batch row {index + 1}, column {offset + 1}")
+            for offset, cell in enumerate(row)
+        )
+        article_id, id_characters, id_bytes = _bounded_metadata(
+            raw_article_id,
+            label=f"Batch row {index + 1} article ID",
+            max_characters=MAX_ARTICLE_ID_CHARS,
+            max_bytes=MAX_ARTICLE_ID_BYTES,
+        )
+        timestamp, timestamp_characters, timestamp_bytes = _bounded_metadata(
+            raw_timestamp,
+            label=f"Batch row {index + 1} publication timestamp",
+            max_characters=MAX_TIMESTAMP_CHARS,
+            max_bytes=MAX_TIMESTAMP_BYTES,
+        )
+        source, source_characters, source_bytes = _bounded_metadata(
+            raw_source,
+            label=f"Batch row {index + 1} source",
+            max_characters=MAX_SOURCE_CHARS,
+            max_bytes=MAX_SOURCE_BYTES,
+        )
+        text_characters, text_bytes = _validate_article_size(
+            raw_text, label=f"Batch row {index + 1} article"
+        )
+        text = raw_text.strip()
+
+        metadata_characters = id_characters + timestamp_characters + source_characters
+        metadata_bytes = id_bytes + timestamp_bytes + source_bytes
+        total_metadata_characters += metadata_characters
+        total_metadata_bytes += metadata_bytes
+        total_text_characters += text_characters
+        total_text_bytes += text_bytes
+        total_content_characters = total_metadata_characters + total_text_characters
+        total_content_bytes = total_metadata_bytes + total_text_bytes
+
+        if total_metadata_characters > MAX_BATCH_METADATA_CHARS:
+            raise gr.Error(
+                "Batch metadata exceeds the "
+                f"{MAX_BATCH_METADATA_CHARS:,}-character aggregate limit."
+            )
+        if total_metadata_bytes > MAX_BATCH_METADATA_BYTES:
+            raise gr.Error(
+                "Batch metadata exceeds the "
+                f"{MAX_BATCH_METADATA_BYTES:,}-byte aggregate UTF-8 limit."
+            )
+        if total_text_characters > MAX_BATCH_CHARS:
+            raise gr.Error(
+                f"Batch article text exceeds the {MAX_BATCH_CHARS:,}-character "
+                "aggregate limit."
+            )
+        if total_text_bytes > MAX_BATCH_BYTES:
+            raise gr.Error(
+                f"Batch article text exceeds the {MAX_BATCH_BYTES:,}-byte "
+                "aggregate UTF-8 limit."
+            )
+        if total_content_characters > MAX_BATCH_CONTENT_CHARS:
+            raise gr.Error(
+                "Combined batch article and metadata content exceeds the "
+                f"{MAX_BATCH_CONTENT_CHARS:,}-character limit."
+            )
+        if total_content_bytes > MAX_BATCH_CONTENT_BYTES:
+            raise gr.Error(
+                "Combined batch article and metadata content exceeds the "
+                f"{MAX_BATCH_CONTENT_BYTES:,}-byte UTF-8 limit."
+            )
+
+        if not any((article_id, timestamp, source, text)):
+            continue
+        if not text:
+            raise gr.Error(f"Batch row {index + 1} has no article text.")
+        if not timestamp:
+            raise gr.Error(f"Batch row {index + 1} has no timestamp.")
+        normalized.append(
+            (article_id or f"row-{index}", timestamp, source or "demo", text)
+        )
+
+    if not normalized:
+        raise gr.Error("Add at least one complete batch row.")
+    try:
+        predictions = _engine().predict_batch(
+            [row[3] for row in normalized],
+            timestamps=[row[1] for row in normalized],
+            article_ids=[row[0] for row in normalized],
+            sources=[row[2] for row in normalized],
+        )
+    except (TypeError, ValueError) as exc:
+        raise gr.Error(
+            "A batch row is invalid. Check that every publication timestamp is "
+            "valid ISO 8601 text."
+        ) from exc
+
+    summaries = [prediction.summary() for prediction in predictions]
+    table = [
+        [
+            summary["article_id"],
+            summary["status"],
+            str(summary["accepted"]),
+            ", ".join(summary["relevant_to"]),
+            summary["why"],
+        ]
+        for summary in summaries
+    ]
+    relevant = sum(summary["status"] == "relevant" for summary in summaries)
+    review = sum(summary["status"] == "needs_review" for summary in summaries)
+    no_match = len(summaries) - relevant - review
+    metrics = {
+        "rows": len(summaries),
+        "relevant": relevant,
+        "needs_review": review,
+        "no_configured_match": no_match,
+        "taxonomy_fingerprint": _engine().taxonomy.fingerprint,
+    }
+    return table, metrics, _download_file(summaries, suffix=".jsonl")
+
+
+def build_demo() -> gr.Blocks:
+    """Build the human-facing UI and named Gradio API endpoints."""
+
+    blocks_options: dict[str, Any] = {
+        "title": "RANGE",
+        "fill_width": True,
+        "delete_cache": (60, 300),
+    }
+    if GRADIO_MAJOR < 6:
+        blocks_options.update(css=CSS, theme=THEME)
+
+    def build_content() -> None:
+        with gr.Tab("Screen one article"):
+            gr.Markdown(
+                "### Check an article\n"
+                "Paste the text and add its publication time. Time is required so "
+                "RANGE can apply time-valid names and relationships; it is not "
+                "used to forecast prices."
+            )
+            with gr.Row():
+                with gr.Column(scale=5):
+                    article = gr.Textbox(
+                        label="Article text",
+                        lines=13,
+                        value=SINGLE_EXAMPLES[0][0],
+                        placeholder="Paste a headline, excerpt, or full article...",
+                        max_length=MAX_ARTICLE_CHARS,
+                    )
+                    with gr.Row():
+                        timestamp = gr.Textbox(
+                            label="Publication timestamp",
+                            value=SINGLE_EXAMPLES[0][1],
+                            info="Required · ISO 8601; include an offset when known.",
+                            max_length=MAX_TIMESTAMP_CHARS,
+                        )
+                    with gr.Accordion("Optional article metadata", open=False):
+                        gr.Markdown(
+                            "Article ID and source make exported records easier to join "
+                            "back to your data. They do not change text matching."
+                        )
+                        with gr.Row():
+                            article_id = gr.Textbox(
+                                label="Article ID",
+                                value=SINGLE_EXAMPLES[0][2],
+                                max_length=MAX_ARTICLE_ID_CHARS,
+                            )
+                            source = gr.Textbox(
+                                label="Source",
+                                value=SINGLE_EXAMPLES[0][3],
+                                max_length=MAX_SOURCE_CHARS,
+                            )
+                    analyze = gr.Button("Check relevance", variant="primary")
+                with gr.Column(scale=4):
+                    status = gr.HTML(INITIAL_STATUS_HTML)
+                    with gr.Accordion("Developer output and download", open=False):
+                        summary = gr.JSON(label="Application-ready summary")
+                        result_file = gr.File(
+                            label="Download evidence record (article text omitted)"
+                        )
+
+            example_options: dict[str, Any] = {
+                "examples": SINGLE_EXAMPLES,
+                "inputs": [article, timestamp, article_id, source],
+                "label": "Try a representative scenario",
+                "cache_examples": False,
+            }
+            if GRADIO_MAJOR >= 6:
+                example_options["example_labels"] = [row[0] for row in ARTICLE_EXAMPLES]
+            gr.Examples(**example_options)
+
+            gr.Markdown(
+                "### Evidence in the article\n"
+                "Highlights distinguish evidence that supported the result from "
+                "unresolved evidence paths and matches rejected by context checks."
+            )
+            highlighted = gr.HTML(
+                '<div class="article-preview empty-preview">Run the screen to see '
+                "matched evidence in its original context.</div>"
+            )
+            evidence = gr.Dataframe(
+                headers=EVIDENCE_HEADERS,
+                datatype=["str"] * len(EVIDENCE_HEADERS),
+                interactive=False,
+                label="Evidence and rule path",
+            )
+            with gr.Accordion("Why RANGE returned this result", open=True):
+                explanation = gr.Textbox(lines=16, label=None)
+            with gr.Accordion("Evidence record (article text omitted)", open=False):
+                audit_json = gr.Code(language="json", lines=24, label=None)
+            with gr.Accordion("Mermaid evidence-flow source (developer)", open=False):
+                diagram = gr.Code(language="markdown", lines=20, label=None)
+
+            analyze.click(
+                fn=analyze_article,
+                inputs=[article, timestamp, article_id, source],
+                outputs=[
+                    status,
+                    highlighted,
+                    summary,
+                    evidence,
+                    explanation,
+                    audit_json,
+                    diagram,
+                    result_file,
+                ],
+                api_name="analyze",
+                scroll_to_output=True,
+                concurrency_limit=1,
+                concurrency_id="range-cpu",
+            )
+
+        with gr.Tab("Batch demo (up to 100)"):
+            gr.Markdown(
+                "This is the rich, explainable demo path—not the package's fastest "
+                "compact benchmark path. Up to 100 rows; 20,000 characters / "
+                "80,000 UTF-8 bytes per article; "
+                "200,000 characters / 800,000 bytes per batch. Package APIs are designed "
+                "for larger batches."
+            )
+            batch_input = gr.Dataframe(
+                headers=["article_id", "timestamp", "source", "text"],
+                datatype=["str", "str", "str", "str"],
+                value=BATCH_ROWS,
+                **(
+                    {
+                        "row_count": len(BATCH_ROWS),
+                        "column_count": 4,
+                    }
+                    if GRADIO_MAJOR >= 6
+                    else {
+                        "row_count": (len(BATCH_ROWS), "dynamic"),
+                        "col_count": (4, "fixed"),
+                    }
+                ),
+                type="array",
+                interactive=True,
+                label="Timestamped articles",
+            )
+            screen = gr.Button("Screen batch", variant="primary")
+            with gr.Row():
+                batch_results = gr.Dataframe(
+                    headers=BATCH_HEADERS,
+                    datatype=["str"] * len(BATCH_HEADERS),
+                    interactive=False,
+                    label="Screening results",
+                )
+                batch_metrics = gr.JSON(label="Batch summary")
+            batch_file = gr.File(label="Download summaries as JSONL")
+            screen.click(
+                fn=analyze_batch,
+                inputs=batch_input,
+                outputs=[batch_results, batch_metrics, batch_file],
+                api_name="batch",
+                concurrency_limit=1,
+                concurrency_id="range-cpu",
+            )
+
+        with gr.Tab("How it works"):
+            gr.Markdown(ABOUT)
+            gr.Markdown(
+                "The named API endpoints are `/analyze` and `/batch`. After deployment "
+                "as a compatible Hugging Face Space, the Space also exposes its generated "
+                "API documentation and `agents.md` instructions for coding agents."
+            )
+
+        gr.Markdown(
+            "---\n"
+            '<div class="privacy-note"><strong>Research alpha · privacy notice.</strong> '
+            "RANGE records configured evidence; it does not provide investment "
+            "advice or a forecast. In a hosted Space, submitted text and generated "
+            "downloads are processed temporarily on the Space host. Do not submit "
+            "private, licensed, or confidential text unless you have permission.</div>"
+        )
+
+    with gr.Blocks(**blocks_options) as demo:
+        gr.HTML(HERO_HTML, elem_classes=["hero-host"])
+        with gr.Column(elem_classes=["content-shell"]):
+            build_content()
+    return demo
+
+
+demo = build_demo()
+
+
+if __name__ == "__main__":
+    launch_options: dict[str, Any] = {
+        "server_name": os.environ.get("GRADIO_SERVER_NAME", "0.0.0.0"),
+        "server_port": int(os.environ.get("GRADIO_SERVER_PORT", "7860")),
+        "show_error": _local_error_details_enabled(),
+        "app_kwargs": {
+            "middleware": [
+                Middleware(
+                    RequestBodyLimitMiddleware,
+                    max_body_size=MAX_HTTP_REQUEST_BYTES,
+                )
+            ]
+        },
+    }
+    if GRADIO_MAJOR >= 6:
+        launch_options.update(css=CSS, theme=THEME)
+    demo.queue(api_open=False, max_size=32).launch(**launch_options)

docs/attention2alpha-compatibility-review.md

@@ -0,0 +1,46 @@
+# Attention2Alpha compatibility-change safety review
+
+Status: **safe to retain; no revert recommended**
+
+Scope: non-package files changed in PR #157 while preparing the standalone RANGE
+package and its validation gates.
+
+This review distinguishes narrow compatibility and correctness repairs from changes to
+the trading or learning objective. The reviewed edits do not alter the RANGE
+taxonomy and do not redefine Attention2Alpha reward, order execution, portfolio
+accounting, replay semantics, or the policy-learning objective.
+
+## File review
+
+| file | change | safety assessment |
+| --- | --- | --- |
+| `attention2alpha/data_split.py` | preserves opaque string split keys instead of coercing them to timestamps | correct for fraction-mode and synthetic indexes; timestamp inputs retain existing handling |
+| `attention2alpha/embeddings/embedding_base.py` | serializes optional configuration objects without importing full optional stacks; makes checkpoint-probe publication failure-safe; clarifies validation errors | reduces import coupling and prevents a stale probe from describing an incomplete artifact |
+| `attention2alpha/embeddings/embedding_flair.py` | supports legacy and lightweight adapters and validates persisted round-trip probes on legacy loads | compatibility hardening; production `nn.Module` behavior remains supported |
+| `attention2alpha/environments/leveraged_etf_portfolio_env.py` | permits validation with W&B disabled while re-raising failures when an active run exists | reporting-path resilience only; no trade or reward calculation changes |
+| `attention2alpha/state_features.py` | uses `min(2, window)` for rolling standard deviation | fixes the invalid `window=1, min_periods=2` case while preserving behavior for windows of two or more |
+| `attention2alpha/train_eval.py` | filters loader keyword arguments against legacy signatures, restores fallback metadata, and reuses the production order-matrix builder for simple adapters | compatibility and best-effort reporting improvements; no training-objective change |
+
+## Risk notes
+
+The W&B guard catches a broad exception because W&B versions expose different
+uninitialized-run failures. It re-raises when `wandb.run` exists, so failures during an
+active tracked run are not silently hidden. A future cleanup may narrow the exception
+after the supported W&B range is frozen, but the current behavior is safe for this PR.
+
+The one-period rolling-volatility change is mathematically well-defined: sample
+standard deviation remains `NaN` until enough observations exist, but Pandas no longer
+rejects an impossible `min_periods` setting.
+
+## Evidence
+
+The repository deterministic suite exercises checkpoint serialization, round-trip
+validation, train/eval compatibility, state features, and environment guards. The
+package workflow is separate and verifies that the RANGE wheel does not import the
+Attention2Alpha package.
+
+## Decision
+
+Keep the changes. When RANGE moves to a dedicated repository, copy only the package
+and `app/` sources; these monorepo compatibility repairs remain part of Attention2Alpha
+history rather than becoming dependencies of the standalone package.

docs/performance.md

@@ -0,0 +1,83 @@
+# Performance and architecture
+
+RANGE is optimized as an exact information-retrieval system. It is not a language
+model and it does not use an external inference service.
+
+## Shipping path
+
+```text
+Python API
+  -> immutable taxonomy and compiled matcher state
+  -> native normalization and Aho-Corasick scan
+  -> identity and effective-date resolution
+  -> evidence-path construction
+  -> rich, compact, or Arrow result
+```
+
+The implementation combines:
+
+1. **Aho-Corasick multi-pattern matching in Rust.** Configured phrases are compiled
+   into automata so the article is not rescanned by a Python loop for every term.
+2. **Rayon parallelism.** Independent articles are partitioned across CPU workers.
+3. **Worker-local scratch state.** Temporary buffers are reused within worker loops.
+4. **ASCII specialization with frozen Unicode fallback.** Common news text avoids
+   unnecessary general-case work while non-ASCII behavior remains versioned.
+5. **Sparse compact outputs.** The common no-match case is represented implicitly.
+6. **Arrow integration.** Columnar text can remain columnar across the screening
+   boundary instead of becoming one Python input object per row.
+7. **Immutable reusable engine state.** Taxonomy parsing and matcher construction are
+   paid at engine initialization rather than repeated for every article.
+
+## Research path
+
+The surrounding research repository records a staged optimization program covering:
+
+- correctness-frozen Python baselines;
+- native phrase matching;
+- fused compact result construction;
+- sparse outputs;
+- Arrow input and output;
+- multicore scale-out and saturation tests;
+- distributed and dataframe integration;
+- alternative matchers; and
+- experimental GPU screening.
+
+The public alpha deliberately ships only the exact CPU/Rust backend. A faster
+experimental stage is not a package feature unless it preserves the frozen decision
+contract and has a supportable build and runtime story.
+
+## What to time
+
+Different measurements answer different questions.
+
+| measurement | includes |
+| --- | --- |
+| classification core | normalization, matching, and compact decision construction |
+| rich prediction | Python article objects, full evidence lineage, and explanation-ready results |
+| Arrow screening | Arrow ingestion and sparse Arrow facts |
+| end-to-end pipeline | data loading, preprocessing, screening, conversion, and downstream work |
+
+Do not compare a classification-core number with an end-to-end application number.
+
+For reproducible timing:
+
+- construct and warm the engine before the measured loop;
+- record package, taxonomy, Python, compiler, CPU, thread, and dataset revisions;
+- separate data loading from classification unless the claim is end-to-end;
+- keep conversion to Python objects outside an Arrow-core timing claim;
+- report article counts and total text bytes, not only articles per second;
+- use repeated, counterbalanced runs when comparing implementations; and
+- retain raw results and correctness digests.
+
+## Claim boundary
+
+Throughput depends on article length, taxonomy size, hit rate, worker count, CPU,
+memory bandwidth, input representation, and whether rich Python results are requested.
+Repository benchmarks are evidence for their recorded environment, not a guarantee for
+every host or workload.
+
+The strongest portable claim for `0.1.0a1` is architectural:
+
+> Relevance replaces per-pattern Python work and neural inference with compiled
+> multi-pattern CPU retrieval, parallel article processing, and sparse or columnar
+> result paths while preserving a traceable evidence contract.

docs/readme-research.md

@@ -0,0 +1,65 @@
+# README and demo research notes
+
+This note records the presentation research behind the `0.1.0a1` README and staged
+Hugging Face Space. It is not a benchmark claim and it does not change the taxonomy or
+runtime contract.
+
+## Sources reviewed
+
+The review covered the GitHub monthly trending page and representative high-quality
+project READMEs with adjacent presentation problems:
+
+- [GitHub Trending, monthly](https://github.com/trending?since=monthly): current
+  repository presentation patterns.
+- [Polars](https://github.com/pola-rs/polars): performance-oriented data tooling with
+  a concise value proposition and evidence-linked benchmarks.
+- [DuckDB](https://github.com/duckdb/duckdb): immediate installation and runnable
+  examples before deeper architecture.
+- [OpenBB](https://github.com/OpenBB-finance/OpenBB): finance-specific positioning,
+  clear audience, product surfaces, and documentation paths.
+- [FinanceToolkit](https://github.com/JerBouma/FinanceToolkit): finance-oriented
+  examples, scope, and discoverable feature groups.
+- [Hugging Face Docker Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
+  and the [coding-agent setup document](https://huggingface.co/new-space/agents.md):
+  deployment metadata, Docker runtime expectations, and agent API discovery.
+
+The review was conducted on 2026-09-02. Trending content changes over time; the goal
+was to extract durable communication patterns rather than copy rankings or wording.
+
+## Patterns applied
+
+| observed pattern | application in Relevance |
+| --- | --- |
+| one-sentence value proposition | “Fast financial-news screening that shows its work.” |
+| show a useful result early | the README opens with real quickstart stdout |
+| put runnable code before exhaustive reference | a complete one-article example appears near the top |
+| explain performance mechanistically | Rust, automata, Rayon, sparse output, and Arrow are mapped to their practical effects |
+| separate product surfaces by user goal | the README distinguishes rich, compact, Arrow, and ranking paths |
+| link performance claims to evidence | claims are bounded to recorded research stages and environments |
+| state boundaries plainly | relevance is separated from sentiment, materiality, prediction, and advice |
+| make the demo self-explanatory | the Space has curated examples, evidence highlights, lineage, downloads, and named APIs |
+| keep deployment reproducible | the Space exporter creates a deterministic source bundle and SHA-256 manifest |
+| avoid decorative clutter | one Space-card emoji; no emoji-heavy package documentation |
+
+## Marketing standard
+
+The README is intentionally specific rather than superlative. It explains why the
+system can be fast and traceable, but it does not claim to be the fastest system in all
+settings. It shows the output contract before implementation details and keeps
+limitations close to the value proposition.
+
+The intended audience is:
+
+- financial-data and news-ingestion engineers;
+- quantitative researchers building candidate-selection pipelines;
+- analysts who need literal evidence and provenance;
+- researchers comparing exact retrieval with model-based classifiers; and
+- teams that need a deterministic first-stage filter before more expensive NLP.
+
+## Items intentionally omitted
+
+- unqualified “blazing fast” or “state of the art” language;
+- benchmark numbers without the host, stage, dataset, and repetition design;
+- claims that rule-based relevance is semantically complete;
+- claims that a relevant article predicts price direction;
+- a published package badge or live Space badge before either artifact exists.

docs/release.md

@@ -0,0 +1,81 @@
+# RANGE 0.1.0a1 release-candidate contract
+
+This directory is the authoritative source for the **RANGE** research alpha.
+
+## Identity
+
+- Product: `RANGE`
+- Distribution: `range-news`
+- Import namespace: `range_news`
+- Version: `0.1.0a1`
+- Supported runtime: CPython 3.10
+- Supported backend: CPU
+- License: MIT
+- Publication state: not published
+
+The distribution name is descriptive while the product name remains RANGE.
+
+## Required artifacts
+
+A candidate build must produce:
+
+- a Linux wheel and a Windows wheel;
+- one source distribution;
+- bundled taxonomy YAML;
+- bundled frozen Unicode tables;
+- the native extension;
+- `LICENSE`, `README.md`, `CHANGELOG.md`, and `CITATION.cff`; and
+- the `app/` Space scaffold, Docker build, offline exporter, and validator in the
+  source distribution.
+
+## Required validation
+
+CI is deliberately small and manually invoked. The `range-news-release-candidate`
+workflow has only two jobs:
+
+1. **Linux package + Space smoke** validates source syntax, the Space scaffold, the
+   Rust dependency lock, wheel/sdist metadata and contents, clean installations,
+   public contracts, README output, the exported Docker context, the running Gradio
+   service, and the named `/analyze` and `/batch` endpoints.
+2. **Windows package smoke** validates the native Windows artifact, source distribution,
+   metadata and contents, clean installations, public contracts, PyArrow support, and
+   README output.
+
+The broader Attention2Alpha and historical acceleration suites are not package-release
+gates. They remain available through the separate manual/main-only `repository-tests`
+workflow.
+
+## Why the workflow is manual
+
+While RANGE remains inside a larger private monorepo, every feature-branch push can
+otherwise produce duplicate `push` and `pull_request` runs. Manual invocation keeps the
+PR readable and conserves hosted-runner minutes while preserving the checks that matter
+before publication or final technical sign-off.
+
+## Explicit no-publish boundary
+
+The repository contains no PyPI token, trusted-publisher deployment job, release tag,
+Space creation step, or upload command for this package. CI artifacts are uploaded only
+to the associated GitHub Actions run for inspection. The Space exporter writes only to
+a local directory.
+
+Publishing requires a separate, explicit human decision after:
+
+- ownership and license review;
+- inspection of both platform artifacts;
+- confirmation of the final repository and documentation URLs;
+- review of the public Space privacy notice and input limits;
+- a clean release commit;
+- a version and tag decision; and
+- intentional package-index and/or Space deployment workflows added in a later change.
+
+## Alpha support boundary
+
+`0.1.0a1` makes a narrow claim:
+
+> An exact, CPU-first, research-alpha package for traceable financial-news relevance
+> screening against a versioned general-economy taxonomy.
+
+It does not claim complete semantic recall, investment usefulness, universal
+throughput, Python-version portability beyond 3.10, or paper-grade performance
+generalization.

docs/taxonomy.md

@@ -0,0 +1,194 @@
+# 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_news 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_news 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_news 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.

docs/technical-signoff.md

@@ -0,0 +1,53 @@
+# RANGE 0.1.0a1 technical sign-off
+
+This document defines the bounded technical sign-off for the unpublished research
+alpha. It does not authorize publication, tagging, release creation, Space deployment,
+or merge.
+
+## Identity
+
+- Product: **RANGE**
+- Distribution: `range-news`
+- Python namespace: `range_news`
+- Native Rust crate: `range_news_native`
+- Version: `0.1.0a1`
+- Runtime: CPython 3.10
+- Shipping backend: exact CPU/Rust
+
+Shipping source, wheels, and source distributions must not contain retired package
+identifiers. The repository URL may retain the parent repository's historical name;
+that is not a package identity.
+
+## Required current-head evidence
+
+Technical sign-off intentionally has only two required jobs. Manually run the
+`range-news-release-candidate` workflow on the exact commit being reviewed and require:
+
+1. **Linux package + Space smoke** — source validation, Rust lock/format checks, wheel
+   and source-distribution construction, metadata and archive inspection, clean
+   installs, public package contracts, README output verification, deterministic Space
+   export, Docker build, Gradio health check, and `/analyze` and `/batch` endpoint
+   discovery.
+2. **Windows package smoke** — native Windows wheel and source-distribution build,
+   metadata/archive inspection, clean installs, package contracts, PyArrow coverage,
+   and README output verification.
+
+The full Attention2Alpha deterministic suite and historical acceleration suite are not
+RANGE package sign-off gates. They remain available in `repository-tests` for a
+manual run and execute after integration to `main`.
+
+A success recorded for an older commit is not sufficient.
+
+## Taxonomy non-change boundary
+
+README, app, CI, and package-identity work must not change the bundled taxonomy
+configuration, entity catalog, lexical catalog, effective dates, exposure mappings,
+matching rules, or decision behavior. Package presentation and taxonomy design are
+separate contracts.
+
+## No-publish boundary
+
+Passing the manual gate leaves the pull request open and unmerged. It creates no PyPI
+or TestPyPI upload, trusted-publisher relationship, registry credential, Git tag,
+GitHub release, Hugging Face Space, deployment, or automatic merge. Publication
+requires a separate explicit change and human decision.

examples.py

@@ -0,0 +1,55 @@
+"""Curated examples for the RANGE Hugging Face Space demo."""
+
+from __future__ import annotations
+
+ARTICLE_EXAMPLES: tuple[tuple[str, str, str, str], ...] = (
+    (
+        "Relevant · CPI, Federal Reserve, and broad benchmarks",
+        "CPI inflation cooled after the Federal Reserve cut the federal funds rate. "
+        "The S&P 500 and Nasdaq-100 advanced.",
+        "2025-01-15T10:30:00-05:00",
+        "macro-inflation-1",
+    ),
+    (
+        "Relevant · labor-market indicators",
+        "Initial jobless claims rose while nonfarm payroll growth slowed.",
+        "2025-01-16T08:30:00-05:00",
+        "macro-labor-1",
+    ),
+    (
+        "Relevant · rates and credit conditions",
+        "Treasury yields fell and credit spreads narrowed after the policy announcement.",
+        "2025-01-17T14:15:00-05:00",
+        "financial-conditions-1",
+    ),
+    (
+        "Relevant · Russell 2000 benchmark",
+        "The Russell 2000 gained as investors rotated toward smaller companies.",
+        "2025-01-21T11:05:00-05:00",
+        "benchmark-1",
+    ),
+    (
+        "Relevant context · no supported broad exposure",
+        "The software company announced quarterly earnings and a share repurchase.",
+        "2025-01-22T16:05:00-05:00",
+        "company-context-1",
+    ),
+    (
+        "No configured match · local-news control",
+        "The city opened a new public garden after a week of mild weather.",
+        "2025-01-23T09:00:00-05:00",
+        "control-1",
+    ),
+)
+
+SINGLE_EXAMPLES: list[list[str]] = [
+    [text, timestamp, article_id, "demo"]
+    for _label, text, timestamp, article_id in ARTICLE_EXAMPLES
+]
+
+BATCH_ROWS: list[list[str]] = [
+    [article_id, timestamp, "demo", text]
+    for _label, text, timestamp, article_id in ARTICLE_EXAMPLES
+]
+
+__all__ = ["ARTICLE_EXAMPLES", "BATCH_ROWS", "SINGLE_EXAMPLES"]

examples/app.py

@@ -0,0 +1,86 @@
+"""Local Gradio demo for one timestamped economy or financial-news article."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import gradio as gr
+
+from range_news import RelevanceEngine
+
+
+@lru_cache(maxsize=1)
+def _engine() -> RelevanceEngine:
+    return RelevanceEngine()
+
+
+def predict_article(text: str, timestamp: str):
+    """Return a compact decision, explanation, and Mermaid diagram source."""
+
+    if not text or not text.strip():
+        raise gr.Error("Enter article text before running a prediction.")
+    if not timestamp or not timestamp.strip():
+        raise gr.Error("Enter an ISO 8601 publication timestamp.")
+
+    try:
+        prediction = _engine().predict(
+            text,
+            timestamp=timestamp,
+            article_id="interactive-demo",
+            source="gradio-local",
+        )
+    except (TypeError, ValueError) as exc:
+        raise gr.Error(f"The article or timestamp is invalid: {exc}") from exc
+
+    explanation = _engine().explain(prediction, format="text", detail="summary")
+    diagram = _engine().explain(prediction, format="mermaid", detail="summary")
+    return prediction.summary(), explanation, diagram
+
+
+def build_demo() -> gr.Blocks:
+    with gr.Blocks(title="RANGE") as demo:
+        gr.Markdown(
+            "# RANGE\n"
+            "**Rapid Analysis of News for the General Economy**\n\n"
+            "Screen timestamped economic and financial news against the bundled "
+            "general-economy taxonomy. Everything runs in this Python process."
+        )
+        with gr.Row():
+            with gr.Column(scale=3):
+                article = gr.Textbox(
+                    label="Article text",
+                    lines=12,
+                    value=(
+                        "CPI inflation cooled after the Federal Reserve cut the "
+                        "federal funds rate. The S&P 500 advanced."
+                    ),
+                )
+                timestamp = gr.Textbox(
+                    label="Publication timestamp",
+                    value="2025-01-15T10:30:00-05:00",
+                    info="Use ISO 8601 with a UTC offset when possible.",
+                )
+                run = gr.Button("Predict relevance", variant="primary")
+            with gr.Column(scale=2):
+                decision = gr.JSON(label="Decision")
+                explanation = gr.Markdown(label="Evidence explanation")
+
+        diagram = gr.Code(
+            language="markdown",
+            label="Mermaid evidence diagram",
+            lines=16,
+        )
+        run.click(
+            fn=predict_article,
+            inputs=[article, timestamp],
+            outputs=[decision, explanation, diagram],
+            api_name="predict",
+        )
+    return demo
+
+
+demo = build_demo()
+
+
+if __name__ == "__main__":
+    demo.launch()

examples/benchmark_hf.py

@@ -0,0 +1,195 @@
+"""Reproducible CPU/Arrow benchmark on one pinned Hugging Face shard.
+
+Install with ``python -m pip install ".[arrow,benchmark]"`` and accept the
+dataset's access terms before running this script.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import statistics
+import time
+from datetime import datetime, timezone
+
+import pyarrow as pa
+from datasets import load_dataset
+from huggingface_hub import HfApi, get_token, login
+
+from range_news import DefaultTaxonomy, RelevanceEngine, __version__
+
+DATASET = "Brianferrell787/financial-news-multisource"
+REVISION = "c25780f336280adb57c64bda7aed605d065c672d"
+SHARD = "data/sp500_daily_headlines/sp500_daily_headlines.000.parquet"
+
+
+def utc_timestamp(value: str) -> datetime:
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def load_seed() -> tuple[pa.RecordBatch, str]:
+    if get_token() is None:
+        login()
+    info = HfApi().dataset_info(DATASET, revision=REVISION, token=True)
+    if info.sha != REVISION:
+        raise RuntimeError(f"dataset revision drifted: {info.sha}")
+
+    dataset = load_dataset(
+        DATASET,
+        name="data",
+        data_files={"train": SHARD},
+        split="train",
+        revision=REVISION,
+        token=True,
+    ).select_columns(["date", "text"])
+
+    texts = pa.array(dataset["text"], type=pa.string())
+    timestamps = pa.array(
+        [utc_timestamp(value) for value in dataset["date"]],
+        type=pa.timestamp("us", tz="UTC"),
+    )
+    seed = pa.record_batch([texts, timestamps], names=["text", "timestamp"])
+
+    digest = hashlib.sha256()
+    for date, text in zip(dataset["date"], dataset["text"], strict=True):
+        row = json.dumps(
+            [date, text],
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        digest.update(len(row).to_bytes(8, "little"))
+        digest.update(row)
+    return seed, digest.hexdigest()
+
+
+def repeated_batches(
+    seed: pa.RecordBatch,
+    total_rows: int,
+    *,
+    batch_rows: int = 100_000,
+) -> tuple[pa.RecordBatch, ...]:
+    output = []
+    emitted = 0
+    while emitted < total_rows:
+        start = emitted % seed.num_rows
+        take = min(batch_rows, total_rows - emitted, seed.num_rows - start)
+        output.append(seed.slice(start, take))
+        emitted += take
+    return tuple(output)
+
+
+def reader(seed: pa.RecordBatch, batches: tuple[pa.RecordBatch, ...]):
+    return pa.RecordBatchReader.from_batches(seed.schema, batches)
+
+
+def semantic_digest(facts, total_rows: int) -> str:
+    digest = hashlib.sha256(f"rows={total_rows}\n".encode())
+    for row in facts.to_pyarrow().to_pylist():
+        payload = json.dumps(
+            row,
+            sort_keys=True,
+            separators=(",", ":"),
+            default=str,
+        ).encode("utf-8")
+        digest.update(len(payload).to_bytes(8, "little"))
+        digest.update(payload)
+    return digest.hexdigest()
+
+
+def measure(
+    engine: RelevanceEngine,
+    seed: pa.RecordBatch,
+    total_rows: int,
+    *,
+    workers: int,
+    repetitions: int,
+) -> dict[str, object]:
+    prepared = repeated_batches(seed, total_rows)
+    warmup_rows = min(total_rows, 10_000)
+    warmup = repeated_batches(seed, warmup_rows)
+    engine.screen_arrow(reader(seed, warmup), workers=workers, row_count=warmup_rows)
+
+    elapsed = []
+    digests = []
+    exceptions = []
+    for _ in range(repetitions):
+        started = time.perf_counter()
+        facts = engine.screen_arrow(
+            reader(seed, prepared),
+            workers=workers,
+            row_count=total_rows,
+        )
+        elapsed.append(time.perf_counter() - started)
+        digests.append(semantic_digest(facts, total_rows))
+        exceptions.append(facts.exception_count)
+
+    if len(set(digests)) != 1 or len(set(exceptions)) != 1:
+        raise RuntimeError("repetitions produced different semantic outputs")
+
+    median = statistics.median(elapsed)
+    return {
+        "backend": "cpu-rust-arrow",
+        "rows": total_rows,
+        "physical_rows": seed.num_rows,
+        "replication_factor": round(total_rows / seed.num_rows, 3),
+        "workers": workers,
+        "repetitions": repetitions,
+        "median_seconds": round(median, 6),
+        "rows_per_second": round(total_rows / median),
+        "exception_rows": exceptions[0],
+        "output_sha256": digests[0],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--rows",
+        type=int,
+        nargs="+",
+        default=[10_000, 100_000, 1_000_000],
+    )
+    parser.add_argument("--workers", type=int, default=min(10, os.cpu_count() or 1))
+    parser.add_argument("--repetitions", type=int, default=3)
+    args = parser.parse_args()
+
+    seed, seed_sha256 = load_seed()
+    taxonomy = DefaultTaxonomy()
+    engine = RelevanceEngine(taxonomy=taxonomy, workers=args.workers)
+
+    print(
+        json.dumps(
+            {
+                "package": __version__,
+                "taxonomy": taxonomy.fingerprint,
+                "dataset": DATASET,
+                "revision": REVISION,
+                "shard": SHARD,
+                "physical_rows": seed.num_rows,
+                "seed_sha256": seed_sha256,
+            },
+            indent=2,
+        )
+    )
+    for total_rows in args.rows:
+        print(
+            json.dumps(
+                measure(
+                    engine,
+                    seed,
+                    total_rows,
+                    workers=args.workers,
+                    repetitions=args.repetitions,
+                ),
+                sort_keys=True,
+            )
+        )
+
+
+if __name__ == "__main__":
+    main()

examples/custom_taxonomy.py

@@ -0,0 +1,43 @@
+"""Extend the bundled general-economy taxonomy without modifying it in place."""
+
+from __future__ import annotations
+
+import json
+
+from range_news import DefaultTaxonomy, RelevanceEngine
+
+
+def add_regional_indicator(builder) -> None:
+    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="custom-example",
+    )
+
+
+def main() -> None:
+    base = DefaultTaxonomy()
+    custom = base.extend(add_regional_indicator)
+
+    assert base.fingerprint != custom.fingerprint
+    assert "regional-manufacturing-survey" not in base.lexical_rule_ids
+    assert "regional-manufacturing-survey" in custom.lexical_rule_ids
+
+    decision = RelevanceEngine(taxonomy=custom, workers=1).predict(
+        "The regional manufacturing survey weakened sharply.",
+        timestamp="2025-01-15T08:30:00-05:00",
+        article_id="custom-economy-1",
+        source="custom-example",
+    )
+
+    print(json.dumps(decision.summary(), indent=2))
+    print(f"\nBase taxonomy:   {base.fingerprint}")
+    print(f"Custom taxonomy: {custom.fingerprint}")
+
+
+if __name__ == "__main__":
+    main()

examples/quickstart.py

@@ -0,0 +1,26 @@
+"""Run the general-economy example shown in the README."""
+
+from __future__ import annotations
+
+from range_news import RelevanceEngine
+
+
+def main() -> None:
+    engine = RelevanceEngine(workers=1)
+    decision = engine.predict(
+        (
+            "CPI inflation cooled after the Federal Reserve cut the federal funds rate. "
+            "The S&P 500 and Nasdaq-100 advanced."
+        ),
+        timestamp="2025-01-15T10:30:00-05:00",
+        article_id="economy-example",
+        source="example",
+    )
+
+    print("status:", decision.status)
+    print("accepted:", decision.accepted)
+    print("markets:", ", ".join(decision.relevant_to))
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["maturin>=1.13.3,<2"]
+build-backend = "maturin"
+
+[project]
+name = "range-news"
+version = "0.1.0a1"
+description = "RANGE: Rapid Analysis of News for the General Economy."
+readme = "PACKAGE_README.md"
+requires-python = ">=3.10,<3.11"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Brian Ferrell" },
+]
+keywords = [
+  "financial news",
+  "economic news",
+  "information retrieval",
+  "high throughput",
+  "taxonomy",
+  "Arrow",
+  "Rust",
+]
+dependencies = [
+  "PyYAML>=6.0.3,<7",
+  "ahocorasick-rs>=1.0.3,<2",
+  "tzdata>=2026.3; platform_system == 'Windows'",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Rust",
+  "Topic :: Office/Business :: Financial",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+arrow = ["pyarrow>=18"]
+demo = ["gradio>=6.26,<7", "starlette>=1.6,<2"]
+benchmark = [
+  "datasets>=3,<5",
+  "huggingface-hub>=0.27",
+  "pyarrow>=18",
+]
+test = [
+  "pytest>=8",
+  "pyarrow>=18",
+]
+release = [
+  "build>=1.2,<2",
+  "check-wheel-contents>=0.6,<1",
+  "twine>=6,<7",
+]
+
+[tool.maturin]
+bindings = "pyo3"
+auditwheel = "repair"
+python-source = "src"
+python-packages = ["range_news"]
+module-name = "range_news._native"
+include = [
+  { path = "src/range_news/py.typed", format = "wheel" },
+  { path = "src/range_news/_core/configs/*.yml", format = "wheel" },
+  { path = "src/range_news/_core/catalogs/*.yml", format = "wheel" },
+  { path = "Cargo.lock", format = "sdist" },
+  { path = "rust/generated/*.bin", format = "sdist" },
+  { path = "rust/generated/unicode_meta.txt", format = "sdist" },
+  { path = "CHANGELOG.md", format = "sdist" },
+  { path = "CITATION.cff", format = "sdist" },
+  { path = "app/*.py", format = "sdist" },
+  { path = "app/*.md", format = "sdist" },
+  { path = "app/Dockerfile", format = "sdist" },
+  { path = "app/requirements.txt", format = "sdist" },
+  { path = "app/.dockerignore", format = "sdist" },
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers -ra"

requirements.txt

@@ -0,0 +1,4 @@
+starlette==1.6.0
+PyYAML==6.0.3
+ahocorasick-rs==1.0.3
+tzdata==2026.3

rust/core.rs

@@ -0,0 +1,1372 @@
+use aho_corasick::{AhoCorasick, AhoCorasickBuilder, MatchKind};
+use pyo3::exceptions::PyValueError;
+use pyo3::prelude::*;
+use rayon::prelude::*;
+use rayon::ThreadPoolBuilder;
+use std::collections::{HashMap, HashSet};
+
+static UNICODE_INDEX: &[u8] = include_bytes!("generated/unicode_index.bin");
+static UNICODE_POOL: &[u8] = include_bytes!("generated/unicode_pool.bin");
+static PYTHON_WHITESPACE: &[u8] = include_bytes!("generated/python_whitespace.bin");
+
+const ALIAS: u8 = 0;
+const LEXICAL: u8 = 1;
+const CONJUNCTION: u8 = 2;
+
+const FAMILY_NONE: i8 = -1;
+const FAMILY_SP500: i8 = 0;
+const FAMILY_NASDAQ100: i8 = 1;
+const FAMILY_RUSSELL2000: i8 = 2;
+const FAMILY_MARKET_WIDE: i8 = 3;
+
+const ARTICLE_ACCEPTED: u8 = 0;
+const ARTICLE_REJECTED: u8 = 2;
+const EXP_SUPPORTED: u8 = 0;
+const EXP_PLAUSIBLE: u8 = 1;
+const EXP_NOT_SUPPORTED: u8 = 2;
+
+#[derive(Clone)]
+struct ConsumerSpec {
+    kind: u8,
+    a: usize,
+    b: usize,
+    c: usize,
+}
+
+#[derive(Clone, Copy, Eq, PartialEq)]
+enum ExactMode {
+    CaseSensitive,
+    PythonIgnoreCaseAsciiLiteral,
+}
+
+#[derive(Clone)]
+struct ExactSpec {
+    value: Vec<char>,
+    mode: ExactMode,
+    kind: u8,
+    index: usize,
+}
+
+struct ExactAutomaton {
+    automaton: AhoCorasick,
+    pattern_specs: Vec<Vec<usize>>,
+}
+
+struct ExactSpecs {
+    specs: Vec<ExactSpec>,
+    case_sensitive: Option<ExactAutomaton>,
+    ignorecase_ascii: Option<ExactAutomaton>,
+}
+
+#[derive(Clone, Copy)]
+struct ExactByteMatch {
+    spec_index: usize,
+    start: usize,
+    end: usize,
+}
+
+#[derive(Clone)]
+struct ContextRule {
+    window_chars: usize,
+    accept_clauses: Vec<Vec<Vec<u8>>>,
+    reject_terms: Vec<Vec<u8>>,
+}
+
+#[derive(Clone)]
+struct AliasSpec {
+    canonical_group: usize,
+    context_rule: Option<usize>,
+    valid_from_epoch: i64,
+    valid_to_epoch: Option<i64>,
+    family: i8,
+    entity_kind: u8,
+    unresolved_tag: bool,
+}
+
+#[derive(Clone)]
+struct LexicalSpec {
+    context_window_chars: usize,
+    context_terms: Vec<Vec<u8>>,
+    is_event: bool,
+    market_wide_authorized: bool,
+    unresolved_tag: bool,
+    has_event_family: bool,
+}
+
+#[derive(Clone)]
+struct ConjunctionSpec {
+    actor_phrase_count: usize,
+    action_phrase_count: usize,
+    object_phrase_count: usize,
+    scope_phrase_count: usize,
+}
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+struct ObservationKey {
+    kind: u8,
+    index: usize,
+    start: usize,
+    end: usize,
+}
+
+// (row_index, article_status, sp500, nasdaq100, russell2000, market_wide,
+//  observation_count, native_candidate, exact_candidate)
+type FactRow = (usize, u8, u8, u8, u8, u8, usize, bool, bool);
+
+#[derive(Default)]
+struct ScanScratch {
+    chars: Vec<char>,
+    normalized: Vec<u8>,
+    offsets: Vec<usize>,
+    window: Vec<u8>,
+    window_offsets: Vec<usize>,
+    exact_byte_matches: Vec<ExactByteMatch>,
+    exact_matches: Vec<(usize, usize, usize)>,
+    exact_boundaries: Vec<usize>,
+    alias_candidates: Vec<(usize, usize, usize)>,
+    lexical_candidates: Vec<(usize, usize, usize)>,
+    conjunction_hits: HashSet<(usize, usize, usize)>,
+    longest: HashMap<(usize, usize), usize>,
+    observations: HashSet<ObservationKey>,
+}
+
+impl ScanScratch {
+    fn reset(&mut self) {
+        self.chars.clear();
+        self.normalized.clear();
+        self.offsets.clear();
+        self.window.clear();
+        self.window_offsets.clear();
+        self.exact_byte_matches.clear();
+        self.exact_matches.clear();
+        self.exact_boundaries.clear();
+        self.alias_candidates.clear();
+        self.lexical_candidates.clear();
+        self.conjunction_hits.clear();
+        self.longest.clear();
+        self.observations.clear();
+    }
+}
+
+#[inline(always)]
+fn is_python_ascii_space(byte: u8) -> bool {
+    matches!(
+        byte,
+        b' ' | b'\t' | b'\n' | 0x0b | 0x0c | b'\r' | 0x1c..=0x1f
+    )
+}
+
+#[inline(always)]
+fn is_separator_ascii(byte: u8) -> bool {
+    matches!(
+        byte,
+        b'-' | b'.' | b',' | b':' | b';' | b'(' | b')' | b'[' | b']' | b'{' | b'}' | b'/'
+    )
+}
+
+#[inline(always)]
+fn is_token_byte(byte: u8) -> bool {
+    byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_'
+}
+
+#[inline(always)]
+fn is_exact_token_char(ch: char, mode: ExactMode) -> bool {
+    if ch.is_ascii_alphanumeric() || ch == '_' {
+        return true;
+    }
+    // Python's Unicode-aware re.IGNORECASE expands [A-Za-z] to these four
+    // additional code points. They are token characters only for the
+    // python_ignorecase_ascii_literal mode; applying this globally would change
+    // the frozen boundary behavior of case-sensitive exact aliases.
+    matches!(mode, ExactMode::PythonIgnoreCaseAsciiLiteral)
+        && matches!(ch, '\u{0130}' | '\u{0131}' | '\u{017f}' | '\u{212a}')
+}
+
+#[inline(always)]
+fn is_python_space(ch: char) -> bool {
+    let cp = ch as usize;
+    let byte = PYTHON_WHITESPACE[cp >> 3];
+    (byte & (1 << (cp & 7))) != 0
+}
+
+#[inline(always)]
+fn mapped_bytes(ch: char) -> Option<&'static [u8]> {
+    let cp = ch as usize;
+    let base = cp * 4;
+    let offset = u32::from_le_bytes([
+        UNICODE_INDEX[base],
+        UNICODE_INDEX[base + 1],
+        UNICODE_INDEX[base + 2],
+        UNICODE_INDEX[base + 3],
+    ]) as usize;
+    if offset == 0 {
+        return None;
+    }
+    let len = u16::from_le_bytes([UNICODE_POOL[offset], UNICODE_POOL[offset + 1]]) as usize;
+    Some(&UNICODE_POOL[offset + 2..offset + 2 + len])
+}
+
+#[inline(always)]
+fn normalize_post_char(
+    ch: char,
+    source_index: usize,
+    normalized: &mut Vec<u8>,
+    offsets: &mut Vec<usize>,
+    pending_space: &mut bool,
+) {
+    let ch = match ch {
+        '-' | '‐' | '‑' | '‒' | '–' | '—' | '―' | '−' => ' ',
+        '.' | ',' | ':' | ';' | '(' | ')' | '[' | ']' | '{' | '}' | '／' | '/' => ' ',
+        '\'' | '’' | '‘' | '‛' | '`' | '´' => '\'',
+        other => other,
+    };
+    if is_python_space(ch) {
+        *pending_space = !normalized.is_empty();
+        return;
+    }
+    if *pending_space {
+        normalized.push(b' ');
+        offsets.push(source_index);
+        *pending_space = false;
+    }
+    let mut buffer = [0u8; 4];
+    let encoded = ch.encode_utf8(&mut buffer).as_bytes();
+    normalized.extend_from_slice(encoded);
+    offsets.extend(std::iter::repeat(source_index).take(encoded.len()));
+}
+
+fn normalize_source_char(
+    source_character: char,
+    source_index: usize,
+    normalized: &mut Vec<u8>,
+    offsets: &mut Vec<usize>,
+    pending_space: &mut bool,
+) {
+    if source_character.is_ascii() {
+        let mut byte = (source_character as u8).to_ascii_lowercase();
+        if is_separator_ascii(byte) {
+            byte = b' ';
+        } else if byte == b'`' {
+            byte = b'\'';
+        }
+        if is_python_ascii_space(byte) {
+            *pending_space = !normalized.is_empty();
+            return;
+        }
+        if *pending_space {
+            normalized.push(b' ');
+            offsets.push(source_index);
+            *pending_space = false;
+        }
+        normalized.push(byte);
+        offsets.push(source_index);
+    } else if let Some(mapped) = mapped_bytes(source_character) {
+        let mapped = std::str::from_utf8(mapped).expect("generated Unicode pool is valid UTF-8");
+        for character in mapped.chars() {
+            normalize_post_char(character, source_index, normalized, offsets, pending_space);
+        }
+    } else {
+        normalize_post_char(
+            source_character,
+            source_index,
+            normalized,
+            offsets,
+            pending_space,
+        );
+    }
+}
+
+fn normalize_chars_into(
+    chars: &[char],
+    source_base: usize,
+    normalized: &mut Vec<u8>,
+    offsets: &mut Vec<usize>,
+) {
+    normalized.clear();
+    offsets.clear();
+    normalized.reserve(chars.len());
+    offsets.reserve(chars.len());
+    let mut pending_space = false;
+    for (local_index, source_character) in chars.iter().copied().enumerate() {
+        let source_index = source_base + local_index;
+        normalize_source_char(
+            source_character,
+            source_index,
+            normalized,
+            offsets,
+            &mut pending_space,
+        );
+    }
+}
+
+#[inline(always)]
+fn normalize_ascii_byte(mut byte: u8) -> u8 {
+    byte.make_ascii_lowercase();
+    if is_separator_ascii(byte) {
+        b' '
+    } else if byte == b'`' {
+        b'\''
+    } else {
+        byte
+    }
+}
+
+fn normalize_ascii_text_into(text: &str, normalized: &mut Vec<u8>, offsets: &mut Vec<usize>) {
+    debug_assert!(text.is_ascii());
+    let mut pending_space = false;
+    for (source_index, source_byte) in text.bytes().enumerate() {
+        let byte = normalize_ascii_byte(source_byte);
+        if is_python_ascii_space(byte) {
+            pending_space = !normalized.is_empty();
+            continue;
+        }
+        if pending_space {
+            normalized.push(b' ');
+            offsets.push(source_index);
+            pending_space = false;
+        }
+        normalized.push(byte);
+        offsets.push(source_index);
+    }
+}
+
+fn normalize_text_into(
+    text: &str,
+    normalized: &mut Vec<u8>,
+    offsets: &mut Vec<usize>,
+) -> (bool, bool) {
+    normalized.clear();
+    offsets.clear();
+    normalized.reserve(text.len());
+    offsets.reserve(text.len());
+    if text.is_ascii() {
+        normalize_ascii_text_into(text, normalized, offsets);
+        return (true, false);
+    }
+    let mut pending_space = false;
+    let mut all_ascii = true;
+    let mut exceptional_ignorecase = false;
+    for (source_index, source_character) in text.chars().enumerate() {
+        all_ascii &= source_character.is_ascii();
+        exceptional_ignorecase |= matches!(
+            source_character,
+            '\u{0130}' | '\u{0131}' | '\u{017f}' | '\u{212a}'
+        );
+        normalize_source_char(
+            source_character,
+            source_index,
+            normalized,
+            offsets,
+            &mut pending_space,
+        );
+    }
+    (all_ascii, exceptional_ignorecase)
+}
+
+#[inline]
+fn normalized_contains(haystack: &[u8], needle: &[u8]) -> bool {
+    if needle.is_empty() || haystack.len() < needle.len() {
+        return false;
+    }
+    let mut cursor = 0usize;
+    while cursor + needle.len() <= haystack.len() {
+        if let Some(relative) = haystack[cursor..]
+            .windows(needle.len())
+            .position(|window| window == needle)
+        {
+            let start = cursor + relative;
+            let end = start + needle.len();
+            let left_ok = start == 0 || !is_token_byte(haystack[start - 1]);
+            let right_ok = end == haystack.len() || !is_token_byte(haystack[end]);
+            if left_ok && right_ok {
+                return true;
+            }
+            cursor = start + 1;
+        } else {
+            return false;
+        }
+    }
+    false
+}
+
+fn normalized_window_into(
+    chars: &[char],
+    start: usize,
+    end: usize,
+    width: usize,
+    normalized: &mut Vec<u8>,
+    offsets: &mut Vec<usize>,
+) {
+    let left = start.saturating_sub(width);
+    let right = (end + width).min(chars.len());
+    normalize_chars_into(&chars[left..right], left, normalized, offsets);
+}
+
+fn context_status(
+    chars: &[char],
+    start: usize,
+    end: usize,
+    rule: &ContextRule,
+    window: &mut Vec<u8>,
+    window_offsets: &mut Vec<usize>,
+) -> u8 {
+    // 0=satisfied, 1=explicit_collision_exclusion, 2=context_clause_not_satisfied
+    normalized_window_into(chars, start, end, rule.window_chars, window, window_offsets);
+    if rule
+        .reject_terms
+        .iter()
+        .any(|term| normalized_contains(window, term))
+    {
+        return 1;
+    }
+    if rule
+        .accept_clauses
+        .iter()
+        .any(|clause| clause.iter().all(|term| normalized_contains(window, term)))
+    {
+        0
+    } else {
+        2
+    }
+}
+
+#[inline(always)]
+fn py_ignorecase_ascii_literal_eq(pattern: char, observed: char) -> bool {
+    let lower = pattern.to_ascii_lowercase();
+    if observed.is_ascii() {
+        return observed.to_ascii_lowercase() == lower;
+    }
+    match lower {
+        'i' => matches!(observed, 'İ' | 'ı'),
+        's' => observed == 'ſ',
+        'k' => observed == 'K',
+        _ => false,
+    }
+}
+
+fn exact_matches(chars: &[char], spec: &ExactSpec) -> Vec<(usize, usize)> {
+    let width = spec.value.len();
+    if width == 0 || width > chars.len() {
+        return Vec::new();
+    }
+    let mut output = Vec::new();
+    for start in 0..=chars.len() - width {
+        let end = start + width;
+        if start > 0 && is_exact_token_char(chars[start - 1], spec.mode) {
+            continue;
+        }
+        if end < chars.len() && is_exact_token_char(chars[end], spec.mode) {
+            continue;
+        }
+        let matched = spec.value.iter().enumerate().all(|(offset, expected)| {
+            let observed = chars[start + offset];
+            match spec.mode {
+                ExactMode::CaseSensitive => observed == *expected,
+                ExactMode::PythonIgnoreCaseAsciiLiteral => {
+                    py_ignorecase_ascii_literal_eq(*expected, observed)
+                }
+            }
+        });
+        if matched {
+            output.push((start, end));
+        }
+    }
+    output
+}
+
+#[inline(always)]
+fn exact_boundaries_match(text: &str, start: usize, end: usize, mode: ExactMode) -> bool {
+    let left_ok = start == 0
+        || !is_exact_token_char(
+            text[..start]
+                .chars()
+                .next_back()
+                .expect("nonempty exact left boundary"),
+            mode,
+        );
+    let right_ok = end == text.len()
+        || !is_exact_token_char(
+            text[end..]
+                .chars()
+                .next()
+                .expect("nonempty exact right boundary"),
+            mode,
+        );
+    left_ok && right_ok
+}
+
+impl ExactAutomaton {
+    fn append_matches(&self, text: &str, mode: ExactMode, output: &mut Vec<ExactByteMatch>) {
+        for matched in self.automaton.find_overlapping_iter(text.as_bytes()) {
+            let start = matched.start();
+            let end = matched.end();
+            if !exact_boundaries_match(text, start, end, mode) {
+                continue;
+            }
+            for &spec_index in &self.pattern_specs[matched.pattern().as_usize()] {
+                output.push(ExactByteMatch {
+                    spec_index,
+                    start,
+                    end,
+                });
+            }
+        }
+    }
+}
+
+fn build_exact_automaton(
+    specs: &[ExactSpec],
+    mode: ExactMode,
+    ascii_case_insensitive: bool,
+) -> PyResult<Option<ExactAutomaton>> {
+    let mut patterns = Vec::<String>::new();
+    let mut pattern_specs = Vec::<Vec<usize>>::new();
+    let mut pattern_ids = HashMap::<String, usize>::new();
+
+    for (spec_index, spec) in specs.iter().enumerate() {
+        if spec.mode != mode {
+            continue;
+        }
+        let value: String = spec.value.iter().collect();
+        let pattern_key = if ascii_case_insensitive {
+            value.to_ascii_lowercase()
+        } else {
+            value.clone()
+        };
+        if let Some(&pattern_id) = pattern_ids.get(&pattern_key) {
+            pattern_specs[pattern_id].push(spec_index);
+        } else {
+            let pattern_id = patterns.len();
+            pattern_ids.insert(pattern_key, pattern_id);
+            patterns.push(value);
+            pattern_specs.push(vec![spec_index]);
+        }
+    }
+
+    if patterns.is_empty() {
+        return Ok(None);
+    }
+    let automaton = AhoCorasickBuilder::new()
+        .match_kind(MatchKind::Standard)
+        .ascii_case_insensitive(ascii_case_insensitive)
+        .build(&patterns)
+        .map_err(|error| PyValueError::new_err(error.to_string()))?;
+    Ok(Some(ExactAutomaton {
+        automaton,
+        pattern_specs,
+    }))
+}
+
+impl ExactSpecs {
+    fn new(specs: Vec<ExactSpec>) -> PyResult<Self> {
+        let case_sensitive = build_exact_automaton(&specs, ExactMode::CaseSensitive, false)?;
+        let ignorecase_ascii =
+            build_exact_automaton(&specs, ExactMode::PythonIgnoreCaseAsciiLiteral, true)?;
+        Ok(Self {
+            specs,
+            case_sensitive,
+            ignorecase_ascii,
+        })
+    }
+
+    fn append_matching(
+        &self,
+        text: &str,
+        byte_matches: &mut Vec<ExactByteMatch>,
+        output: &mut Vec<(usize, usize, usize)>,
+        exceptional_chars: &mut Vec<char>,
+        boundaries: &mut Vec<usize>,
+        text_is_ascii: bool,
+        exceptional_ignorecase: bool,
+    ) {
+        byte_matches.clear();
+        output.clear();
+        exceptional_chars.clear();
+        boundaries.clear();
+        if let Some(automaton) = &self.case_sensitive {
+            automaton.append_matches(text, ExactMode::CaseSensitive, byte_matches);
+        }
+
+        if !exceptional_ignorecase {
+            if let Some(automaton) = &self.ignorecase_ascii {
+                automaton.append_matches(
+                    text,
+                    ExactMode::PythonIgnoreCaseAsciiLiteral,
+                    byte_matches,
+                );
+            }
+        }
+
+        output.reserve(byte_matches.len());
+        if text_is_ascii {
+            output.extend(
+                byte_matches
+                    .iter()
+                    .copied()
+                    .map(|matched| (matched.spec_index, matched.start, matched.end)),
+            );
+        } else if !byte_matches.is_empty() {
+            // Aho-Corasick reports UTF-8 byte offsets while the frozen Python
+            // surface reports code-point offsets. Build this map only for the
+            // uncommon non-ASCII row that actually produced an exact hit.
+            boundaries.extend(text.char_indices().map(|(offset, _)| offset));
+            boundaries.push(text.len());
+            output.extend(byte_matches.iter().copied().map(|matched| {
+                let start = boundaries
+                    .binary_search(&matched.start)
+                    .expect("exact match starts at a UTF-8 character boundary");
+                let end = boundaries
+                    .binary_search(&matched.end)
+                    .expect("exact match ends at a UTF-8 character boundary");
+                (matched.spec_index, start, end)
+            }));
+        }
+
+        if exceptional_ignorecase {
+            // Python re.IGNORECASE gives ASCII I/S/K four additional Unicode
+            // equivalents (İ, ı, ſ, K). The common ASCII automaton cannot change
+            // byte width while matching, so retain the exact scalar fallback
+            // only for rows that contain one of those exceptional code points.
+            exceptional_chars.extend(text.chars());
+            for (spec_index, spec) in self.specs.iter().enumerate() {
+                if spec.mode != ExactMode::PythonIgnoreCaseAsciiLiteral {
+                    continue;
+                }
+                output.extend(
+                    exact_matches(exceptional_chars, spec)
+                        .into_iter()
+                        .map(|(start, end)| (spec_index, start, end)),
+                );
+            }
+        }
+    }
+
+    #[cfg(test)]
+    fn matching(&self, text: &str) -> Vec<(usize, usize, usize)> {
+        let mut byte_matches = Vec::new();
+        let mut output = Vec::new();
+        let mut exceptional_chars = Vec::new();
+        let mut boundaries = Vec::new();
+        let mut normalized = Vec::new();
+        let mut offsets = Vec::new();
+        let (text_is_ascii, exceptional_ignorecase) =
+            normalize_text_into(text, &mut normalized, &mut offsets);
+        self.append_matching(
+            text,
+            &mut byte_matches,
+            &mut output,
+            &mut exceptional_chars,
+            &mut boundaries,
+            text_is_ascii,
+            exceptional_ignorecase,
+        );
+        output
+    }
+}
+
+fn build_automaton(patterns: &[String]) -> PyResult<AhoCorasick> {
+    if patterns.iter().any(|pattern| pattern.is_empty()) {
+        return Err(PyValueError::new_err("patterns must be non-empty"));
+    }
+    AhoCorasickBuilder::new()
+        .match_kind(MatchKind::Standard)
+        .build(patterns)
+        .map_err(|error| PyValueError::new_err(error.to_string()))
+}
+
+fn scan_one(
+    automaton: &AhoCorasick,
+    pattern_consumers: &[Vec<usize>],
+    consumers: &[ConsumerSpec],
+    exact_specs: &ExactSpecs,
+    aliases: &[AliasSpec],
+    lexical: &[LexicalSpec],
+    contexts: &[ContextRule],
+    conjunctions: &[ConjunctionSpec],
+    text: &str,
+    observed_epoch: i64,
+    row_index: usize,
+    scratch: &mut ScanScratch,
+) -> Option<FactRow> {
+    scratch.reset();
+    let (text_is_ascii, exceptional_ignorecase) =
+        normalize_text_into(text, &mut scratch.normalized, &mut scratch.offsets);
+    let mut native_candidate = false;
+    if !scratch.normalized.is_empty() {
+        for matched in automaton.find_overlapping_iter(&scratch.normalized) {
+            let start = matched.start();
+            let end = matched.end();
+            let left_ok = start == 0 || !is_token_byte(scratch.normalized[start - 1]);
+            let right_ok =
+                end == scratch.normalized.len() || !is_token_byte(scratch.normalized[end]);
+            if !left_ok || !right_ok {
+                continue;
+            }
+            native_candidate = true;
+            let original_start = scratch.offsets[start];
+            let original_end = scratch.offsets[end - 1] + 1;
+            for &consumer_id in &pattern_consumers[matched.pattern().as_usize()] {
+                let spec = &consumers[consumer_id];
+                match spec.kind {
+                    ALIAS => {
+                        scratch
+                            .alias_candidates
+                            .push((spec.a, original_start, original_end));
+                    }
+                    LEXICAL => {
+                        scratch
+                            .lexical_candidates
+                            .push((spec.a, original_start, original_end));
+                    }
+                    CONJUNCTION => {
+                        scratch.conjunction_hits.insert((spec.a, spec.b, spec.c));
+                    }
+                    _ => unreachable!("validated consumer kind"),
+                }
+            }
+        }
+    }
+
+    let mut exact_candidate = false;
+    exact_specs.append_matching(
+        text,
+        &mut scratch.exact_byte_matches,
+        &mut scratch.exact_matches,
+        &mut scratch.chars,
+        &mut scratch.exact_boundaries,
+        text_is_ascii,
+        exceptional_ignorecase,
+    );
+    for &(spec_index, start, end) in &scratch.exact_matches {
+        exact_candidate = true;
+        let spec = &exact_specs.specs[spec_index];
+        match spec.kind {
+            ALIAS => scratch.alias_candidates.push((spec.index, start, end)),
+            LEXICAL => scratch.lexical_candidates.push((spec.index, start, end)),
+            CONJUNCTION => {
+                scratch.conjunction_hits.insert((spec.index, 0, usize::MAX));
+            }
+            _ => unreachable!("validated exact kind"),
+        }
+    }
+
+    if scratch.alias_candidates.is_empty()
+        && scratch.lexical_candidates.is_empty()
+        && scratch.conjunction_hits.is_empty()
+    {
+        return None;
+    }
+
+    // Normalized scanning and the exact automata do not need a materialized
+    // Unicode scalar vector. Build it only after the row produced a consumer;
+    // the common no-fact path therefore performs one traversal and no char Vec
+    // allocation. Exceptional Python ignorecase rows may already have filled it.
+    if scratch.chars.is_empty() && !text.is_empty() {
+        scratch.chars.extend(text.chars());
+    }
+
+    // Longest alias per (canonical_id, start), preserving every alias that ties.
+    for &(alias_index, start, end) in &scratch.alias_candidates {
+        let key = (aliases[alias_index].canonical_group, start);
+        scratch
+            .longest
+            .entry(key)
+            .and_modify(|value| *value = (*value).max(end))
+            .or_insert(end);
+    }
+
+    let mut accepted_nonsemantic = false;
+    let mut accepted_evidence = false;
+    let mut unresolved_exposure = false;
+    let mut unresolved_event = false;
+    let mut supported_mask: u8 = 0;
+
+    for candidate_index in 0..scratch.alias_candidates.len() {
+        let (alias_index, start, end) = scratch.alias_candidates[candidate_index];
+        let spec = &aliases[alias_index];
+        if end < scratch.longest[&(spec.canonical_group, start)] {
+            continue;
+        }
+        let key = ObservationKey {
+            kind: ALIAS,
+            index: alias_index,
+            start,
+            end,
+        };
+        if !scratch.observations.insert(key) {
+            continue;
+        }
+
+        let active = observed_epoch >= spec.valid_from_epoch
+            && spec
+                .valid_to_epoch
+                .map(|until| observed_epoch < until)
+                .unwrap_or(true);
+        if !active {
+            continue;
+        }
+
+        let context_code = if let Some(rule_index) = spec.context_rule {
+            context_status(
+                &scratch.chars,
+                start,
+                end,
+                &contexts[rule_index],
+                &mut scratch.window,
+                &mut scratch.window_offsets,
+            )
+        } else {
+            0
+        };
+        if context_code != 0 {
+            // Frozen exposure unresolved filter excludes explicit collision and
+            // context-clause failures. Missing context cannot occur because the
+            // validated config rejects unknown rules during construction.
+            continue;
+        }
+
+        accepted_nonsemantic = true;
+        if spec.family != FAMILY_NONE && (spec.entity_kind == 0 || spec.entity_kind == 1) {
+            accepted_evidence = true;
+            supported_mask |= 1u8 << (spec.family as u8);
+        } else if spec.unresolved_tag {
+            unresolved_exposure = true;
+        }
+    }
+
+    for candidate_index in 0..scratch.lexical_candidates.len() {
+        let (lexical_index, start, end) = scratch.lexical_candidates[candidate_index];
+        let spec = &lexical[lexical_index];
+        let key = ObservationKey {
+            kind: LEXICAL,
+            index: lexical_index,
+            start,
+            end,
+        };
+        if !scratch.observations.insert(key) {
+            continue;
+        }
+
+        let context_ok = if spec.context_terms.is_empty() {
+            true
+        } else {
+            normalized_window_into(
+                &scratch.chars,
+                start,
+                end,
+                spec.context_window_chars,
+                &mut scratch.window,
+                &mut scratch.window_offsets,
+            );
+            spec.context_terms
+                .iter()
+                .any(|term| normalized_contains(&scratch.window, term))
+        };
+
+        if spec.is_event {
+            if spec.market_wide_authorized {
+                accepted_evidence = true;
+                supported_mask |= 1u8 << FAMILY_MARKET_WIDE;
+            } else {
+                if spec.unresolved_tag {
+                    unresolved_exposure = true;
+                }
+                if spec.has_event_family {
+                    unresolved_event = true;
+                }
+            }
+        } else {
+            if context_ok {
+                accepted_nonsemantic = true;
+            }
+            if spec.market_wide_authorized && context_ok {
+                accepted_evidence = true;
+                supported_mask |= 1u8 << FAMILY_MARKET_WIDE;
+            } else if spec.unresolved_tag {
+                // Matches frozen generic lexical unresolved branch, including a
+                // lexical context failure, whose evidence reason is the generic
+                // identity-resolved-without-path code.
+                unresolved_exposure = true;
+            }
+        }
+    }
+
+    for (rule_index, rule) in conjunctions.iter().enumerate() {
+        let field_has = |field: usize, count: usize| -> bool {
+            (0..count).any(|phrase_index| {
+                scratch
+                    .conjunction_hits
+                    .contains(&(rule_index, field, phrase_index))
+            })
+        };
+        let actor_phrase = field_has(0, rule.actor_phrase_count);
+        let actor_exact = scratch
+            .conjunction_hits
+            .contains(&(rule_index, 0, usize::MAX));
+        let actor = actor_phrase || actor_exact;
+        let action = field_has(1, rule.action_phrase_count);
+        let object = field_has(2, rule.object_phrase_count);
+        let scope = field_has(3, rule.scope_phrase_count);
+        if actor && action && object && scope {
+            // Only one conjunction observation exists per configured rule.
+            scratch.observations.insert(ObservationKey {
+                kind: CONJUNCTION,
+                index: rule_index,
+                start: 0,
+                end: 1,
+            });
+            accepted_evidence = true;
+            supported_mask |= 1u8 << FAMILY_MARKET_WIDE;
+        }
+    }
+
+    if scratch.observations.is_empty() {
+        return None;
+    }
+    let article_status = if accepted_evidence || accepted_nonsemantic || unresolved_event {
+        ARTICLE_ACCEPTED
+    } else {
+        ARTICLE_REJECTED
+    };
+    let completed_elsewhere = supported_mask != 0;
+    let exposure_status = |family: i8| -> u8 {
+        if (supported_mask & (1u8 << (family as u8))) != 0 {
+            EXP_SUPPORTED
+        } else if family != FAMILY_MARKET_WIDE && !completed_elsewhere && unresolved_exposure {
+            EXP_PLAUSIBLE
+        } else {
+            EXP_NOT_SUPPORTED
+        }
+    };
+
+    Some((
+        row_index,
+        article_status,
+        exposure_status(FAMILY_SP500),
+        exposure_status(FAMILY_NASDAQ100),
+        exposure_status(FAMILY_RUSSELL2000),
+        exposure_status(FAMILY_MARKET_WIDE),
+        scratch.observations.len(),
+        native_candidate,
+        exact_candidate,
+    ))
+}
+
+#[pyclass(frozen, module = "range_news._native")]
+struct NativeCompactFactScanner {
+    automaton: AhoCorasick,
+    pattern_consumers: Vec<Vec<usize>>,
+    consumers: Vec<ConsumerSpec>,
+    exact_specs: ExactSpecs,
+    aliases: Vec<AliasSpec>,
+    lexical: Vec<LexicalSpec>,
+    contexts: Vec<ContextRule>,
+    conjunctions: Vec<ConjunctionSpec>,
+}
+
+#[pymethods]
+impl NativeCompactFactScanner {
+    #[new]
+    #[pyo3(signature = (
+        patterns,
+        pattern_consumers,
+        consumers,
+        exact_specs,
+        alias_specs,
+        lexical_specs,
+        context_rules,
+        conjunction_specs
+    ))]
+    fn new(
+        patterns: Vec<String>,
+        pattern_consumers: Vec<Vec<usize>>,
+        consumers: Vec<(u8, usize, usize, usize)>,
+        exact_specs: Vec<(String, String, u8, usize)>,
+        alias_specs: Vec<(usize, i64, Option<i64>, i8, u8, bool, Option<usize>)>,
+        lexical_specs: Vec<(usize, Vec<String>, bool, bool, bool, bool)>,
+        context_rules: Vec<(usize, Vec<Vec<String>>, Vec<String>)>,
+        conjunction_specs: Vec<(usize, usize, usize, usize)>,
+    ) -> PyResult<Self> {
+        if patterns.len() != pattern_consumers.len() {
+            return Err(PyValueError::new_err("pattern_consumers length mismatch"));
+        }
+        let automaton = build_automaton(&patterns)?;
+        let consumers = consumers
+            .into_iter()
+            .map(|(kind, a, b, c)| ConsumerSpec { kind, a, b, c })
+            .collect();
+        let mut parsed_exact = Vec::with_capacity(exact_specs.len());
+        for (value, mode, kind, index) in exact_specs {
+            if value.is_empty() {
+                return Err(PyValueError::new_err("exact value must be non-empty"));
+            }
+            let mode = match mode.as_str() {
+                "case_sensitive" => ExactMode::CaseSensitive,
+                "python_ignorecase_ascii_literal" => {
+                    if !value.is_ascii() {
+                        return Err(PyValueError::new_err("ignorecase literal must be ASCII"));
+                    }
+                    ExactMode::PythonIgnoreCaseAsciiLiteral
+                }
+                _ => return Err(PyValueError::new_err(format!("unknown exact mode: {mode}"))),
+            };
+            parsed_exact.push(ExactSpec {
+                value: value.chars().collect(),
+                mode,
+                kind,
+                index,
+            });
+        }
+        let aliases = alias_specs
+            .into_iter()
+            .map(
+                |(
+                    canonical_group,
+                    valid_from_epoch,
+                    valid_to_epoch,
+                    family,
+                    entity_kind,
+                    unresolved_tag,
+                    context_rule,
+                )| AliasSpec {
+                    canonical_group,
+                    valid_from_epoch,
+                    valid_to_epoch,
+                    family,
+                    entity_kind,
+                    unresolved_tag,
+                    context_rule,
+                },
+            )
+            .collect();
+        let lexical = lexical_specs
+            .into_iter()
+            .map(
+                |(
+                    context_window_chars,
+                    terms,
+                    is_event,
+                    market_wide_authorized,
+                    unresolved_tag,
+                    has_event_family,
+                )| LexicalSpec {
+                    context_window_chars,
+                    context_terms: terms.into_iter().map(String::into_bytes).collect(),
+                    is_event,
+                    market_wide_authorized,
+                    unresolved_tag,
+                    has_event_family,
+                },
+            )
+            .collect();
+        let contexts = context_rules
+            .into_iter()
+            .map(|(window_chars, clauses, rejects)| ContextRule {
+                window_chars,
+                accept_clauses: clauses
+                    .into_iter()
+                    .map(|clause| clause.into_iter().map(String::into_bytes).collect())
+                    .collect(),
+                reject_terms: rejects.into_iter().map(String::into_bytes).collect(),
+            })
+            .collect();
+        let conjunctions = conjunction_specs
+            .into_iter()
+            .map(
+                |(
+                    actor_phrase_count,
+                    action_phrase_count,
+                    object_phrase_count,
+                    scope_phrase_count,
+                )| ConjunctionSpec {
+                    actor_phrase_count,
+                    action_phrase_count,
+                    object_phrase_count,
+                    scope_phrase_count,
+                },
+            )
+            .collect();
+        let exact_specs = ExactSpecs::new(parsed_exact)?;
+        Ok(Self {
+            automaton,
+            pattern_consumers,
+            consumers,
+            exact_specs,
+            aliases,
+            lexical,
+            contexts,
+            conjunctions,
+        })
+    }
+
+    #[pyo3(signature = (texts, epochs, workers=4))]
+    fn screen_facts_batch(
+        &self,
+        py: Python<'_>,
+        texts: Vec<String>,
+        epochs: Vec<i64>,
+        workers: usize,
+    ) -> PyResult<Vec<FactRow>> {
+        if texts.len() != epochs.len() {
+            return Err(PyValueError::new_err("texts/epochs length mismatch"));
+        }
+        if workers == 0 {
+            return Err(PyValueError::new_err("workers must be >= 1"));
+        }
+        let pool = ThreadPoolBuilder::new()
+            .num_threads(workers)
+            .thread_name(|index| format!("news-relevance-worker-{index}"))
+            .build()
+            .map_err(|error| PyValueError::new_err(error.to_string()))?;
+        let automaton = &self.automaton;
+        let pattern_consumers = &self.pattern_consumers;
+        let consumers = &self.consumers;
+        let exact_specs = &self.exact_specs;
+        let aliases = &self.aliases;
+        let lexical = &self.lexical;
+        let contexts = &self.contexts;
+        let conjunctions = &self.conjunctions;
+        Ok(py.detach(move || {
+            pool.install(|| {
+                texts
+                    .par_iter()
+                    .zip(epochs.par_iter())
+                    .enumerate()
+                    .map_init(ScanScratch::default, |scratch, (index, (text, epoch))| {
+                        scan_one(
+                            automaton,
+                            pattern_consumers,
+                            consumers,
+                            exact_specs,
+                            aliases,
+                            lexical,
+                            contexts,
+                            conjunctions,
+                            text,
+                            *epoch,
+                            index,
+                            scratch,
+                        )
+                    })
+                    .filter_map(|row| row)
+                    .collect()
+            })
+        }))
+    }
+}
+
+#[cfg(test)]
+mod exact_automata_tests {
+    use super::*;
+
+    fn spec(value: &str, mode: ExactMode, index: usize) -> ExactSpec {
+        ExactSpec {
+            value: value.chars().collect(),
+            mode,
+            kind: ALIAS,
+            index,
+        }
+    }
+
+    #[test]
+    fn exact_automata_equal_scalar_reference_across_boundaries_and_unicode() {
+        let specs = vec![
+            spec("UPRO", ExactMode::CaseSensitive, 0),
+            spec("QQQ", ExactMode::PythonIgnoreCaseAsciiLiteral, 1),
+            spec("iShares", ExactMode::PythonIgnoreCaseAsciiLiteral, 2),
+            spec("PowerShares", ExactMode::PythonIgnoreCaseAsciiLiteral, 3),
+            // Duplicate literals must still fan out to every configured consumer.
+            spec("SEC", ExactMode::CaseSensitive, 4),
+            spec("SEC", ExactMode::CaseSensitive, 5),
+        ];
+        let matcher = ExactSpecs::new(specs).expect("valid exact automata");
+        let texts = [
+            "UPRO upro QQQ qqq xQQQ QQQx SEC",
+            "é UPRO αQQQ αSEC",
+            "İShares ıSHARES iShares Powerſhares",
+            "İQQQ QQQİ ſQQQ QQQK",
+            "no exact literals here",
+        ];
+
+        for text in texts {
+            let chars: Vec<char> = text.chars().collect();
+            let mut expected = Vec::new();
+            for (spec_index, spec) in matcher.specs.iter().enumerate() {
+                expected.extend(
+                    exact_matches(&chars, spec)
+                        .into_iter()
+                        .map(|(start, end)| (spec_index, start, end)),
+                );
+            }
+            expected.sort_unstable();
+
+            let mut observed = matcher.matching(text);
+            observed.sort_unstable();
+            assert_eq!(observed, expected, "text={text:?}");
+            assert_eq!(!observed.is_empty(), !expected.is_empty());
+        }
+    }
+
+    #[test]
+    fn python_ignorecase_exceptions_remain_token_boundaries() {
+        let matcher = ExactSpecs::new(vec![spec(
+            "QQQ",
+            ExactMode::PythonIgnoreCaseAsciiLiteral,
+            0,
+        )])
+        .expect("valid exact automaton");
+        for text in ["İQQQ", "QQQı", "ſQQQ", "QQQK"] {
+            assert!(matcher.matching(text).is_empty(), "text={text:?}");
+        }
+    }
+
+    #[test]
+    fn direct_text_normalization_matches_character_slice_reference() {
+        let texts = [
+            "ASCII -- punctuation\tand spaces",
+            "Café — ‘quoted’ ／ fullwidth",
+            "Straße İ ı ſ K fi",
+            "\u{001c}leading\u{00a0}and\u{2029}trailing\n",
+            "",
+        ];
+        for text in texts {
+            let chars: Vec<char> = text.chars().collect();
+            let mut expected = Vec::new();
+            let mut expected_offsets = Vec::new();
+            normalize_chars_into(&chars, 0, &mut expected, &mut expected_offsets);
+
+            let mut observed = Vec::new();
+            let mut observed_offsets = Vec::new();
+            let (all_ascii, exceptional_ignorecase) =
+                normalize_text_into(text, &mut observed, &mut observed_offsets);
+            assert_eq!(observed, expected, "text={text:?}");
+            assert_eq!(observed_offsets, expected_offsets, "text={text:?}");
+            assert_eq!(
+                all_ascii,
+                chars.iter().all(|character| character.is_ascii())
+            );
+            assert_eq!(
+                exceptional_ignorecase,
+                chars.iter().any(|character| matches!(
+                    character,
+                    '\u{0130}' | '\u{0131}' | '\u{017f}' | '\u{212a}'
+                )),
+                "text={text:?}"
+            );
+        }
+    }
+
+    fn assert_ascii_normalization_matches_character_reference(bytes: &[u8]) {
+        let text = std::str::from_utf8(bytes).expect("ASCII bytes are valid UTF-8");
+        let chars: Vec<char> = text.chars().collect();
+        let mut expected = Vec::new();
+        let mut expected_offsets = Vec::new();
+        normalize_chars_into(&chars, 0, &mut expected, &mut expected_offsets);
+
+        let mut observed = Vec::new();
+        let mut observed_offsets = Vec::new();
+        let flags = normalize_text_into(text, &mut observed, &mut observed_offsets);
+        assert_eq!(flags, (true, false), "bytes={bytes:?}");
+        assert_eq!(observed, expected, "bytes={bytes:?}");
+        assert_eq!(observed_offsets, expected_offsets, "bytes={bytes:?}");
+    }
+
+    #[test]
+    fn ascii_byte_path_matches_character_reference_exhaustively() {
+        assert_ascii_normalization_matches_character_reference(b"");
+        for first in 0u8..=0x7f {
+            assert_ascii_normalization_matches_character_reference(&[first]);
+            assert_ascii_normalization_matches_character_reference(&[b'x', first, b'y']);
+            for second in 0u8..=0x7f {
+                assert_ascii_normalization_matches_character_reference(&[first, second]);
+                assert_ascii_normalization_matches_character_reference(&[
+                    b'x', first, second, b'y',
+                ]);
+            }
+        }
+    }
+
+    #[test]
+    fn ascii_byte_path_preserves_collapse_and_control_semantics() {
+        let tricky = [
+            b' ', b'-', b'\t', b'A', b'`', b'B', b'.', b'/', b' ', 0x00, b'\\', 0x7f, b' ', b'\n',
+        ];
+        assert_ascii_normalization_matches_character_reference(&tricky);
+
+        let mut normalized = Vec::new();
+        let mut offsets = Vec::new();
+        let text = std::str::from_utf8(&tricky).expect("ASCII bytes are valid UTF-8");
+        assert_eq!(
+            normalize_text_into(text, &mut normalized, &mut offsets),
+            (true, false)
+        );
+        assert_eq!(normalized, b"a'b \0\\\x7f");
+        assert_eq!(offsets, [3, 4, 5, 9, 9, 10, 11]);
+
+        let python_ascii_whitespace = [
+            b' ', b'\t', b'\n', 0x0b, 0x0c, b'\r', 0x1c, 0x1d, 0x1e, 0x1f,
+        ];
+        let separators = [
+            b'-', b'.', b',', b':', b';', b'(', b')', b'[', b']', b'{', b'}', b'/',
+        ];
+        let mut runs = vec![b'A'];
+        runs.extend_from_slice(&python_ascii_whitespace);
+        runs.extend_from_slice(&separators);
+        runs.push(b'Z');
+        assert_ascii_normalization_matches_character_reference(&runs);
+        normalize_text_into(
+            std::str::from_utf8(&runs).expect("ASCII bytes are valid UTF-8"),
+            &mut normalized,
+            &mut offsets,
+        );
+        assert_eq!(normalized, b"a z");
+        assert_eq!(offsets, [0, runs.len() - 1, runs.len() - 1]);
+    }
+
+    #[test]
+    fn reused_scan_scratch_does_not_leak_candidates_between_rows() {
+        let automaton = build_automaton(&["alpha".to_string()]).expect("valid automaton");
+        let pattern_consumers = vec![vec![0]];
+        let consumers = vec![ConsumerSpec {
+            kind: ALIAS,
+            a: 0,
+            b: 0,
+            c: 0,
+        }];
+        let exact_specs = ExactSpecs::new(Vec::new()).expect("empty exact specs are valid");
+        let aliases = vec![AliasSpec {
+            canonical_group: 0,
+            context_rule: None,
+            valid_from_epoch: 0,
+            valid_to_epoch: None,
+            family: FAMILY_SP500,
+            entity_kind: 0,
+            unresolved_tag: false,
+        }];
+        let mut scratch = ScanScratch::default();
+        let scan = |text: &str, row_index: usize, scratch: &mut ScanScratch| {
+            scan_one(
+                &automaton,
+                &pattern_consumers,
+                &consumers,
+                &exact_specs,
+                &aliases,
+                &[],
+                &[],
+                &[],
+                text,
+                1,
+                row_index,
+                scratch,
+            )
+        };
+
+        let first = scan("Alpha rises", 0, &mut scratch).expect("first row matches");
+        assert_eq!(first.0, 0);
+        assert_eq!(first.6, 1);
+        assert!(scan("nothing relevant", 1, &mut scratch).is_none());
+        let third = scan("alpha again", 2, &mut scratch).expect("third row matches");
+        assert_eq!(third.0, 2);
+        assert_eq!(third.6, 1);
+    }
+}

rust/generated/python_whitespace.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6c314375b6c075589b515139e50068d72c0cbd7daf4246e555a9dcfc9748ecc9
+size 139264

rust/generated/unicode_index.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fe152ac184aa77c40d0f040ba725140b17d845bae9fae255b2b3d3c43bb79c8f
+size 4456448

rust/generated/unicode_meta.txt

@@ -0,0 +1 @@
+{"index_bytes":4456448,"mapped_codepoints":6179,"normalization":"per-codepoint NFKC then casefold","pool_bytes":29973,"python":"3.10.18","sha256":"a85f34b8ec50dfe2c5cd7a38b7ed38e65df635a1b197cf7607fce8f5fb5c23ed","unicode":"13.0.0","unicode_limit":1114112,"whitespace_bytes":139264}

rust/generated/unicode_pool.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:109a8da1563408ad1da82919a5dfa1ab9fa18870f0f4d22e2818857b5a4fc30f
+size 29973

rust/lib.rs

@@ -0,0 +1,321 @@
+// The Python-list and Arrow entry points share one exact scanning core and ship
+// in a single private extension module.
+include!("core.rs");
+
+use arrow_array::{
+    Array, ArrayRef, BooleanArray, LargeStringArray, RecordBatch, StringArray,
+    TimestampMicrosecondArray, TimestampMillisecondArray, TimestampNanosecondArray,
+    TimestampSecondArray, UInt32Array, UInt64Array, UInt8Array,
+};
+use arrow_schema::{DataType, Field, Schema, TimeUnit};
+use pyo3_arrow::input::AnyRecordBatch;
+use pyo3_arrow::PyRecordBatch;
+use std::sync::{Arc, Mutex, OnceLock};
+
+static ARROW_POOLS: OnceLock<Mutex<HashMap<usize, Arc<rayon::ThreadPool>>>> = OnceLock::new();
+
+fn worker_pool(workers: usize) -> PyResult<Arc<rayon::ThreadPool>> {
+    if workers == 0 {
+        return Err(PyValueError::new_err("workers must be >= 1"));
+    }
+    let pools = ARROW_POOLS.get_or_init(|| Mutex::new(HashMap::new()));
+    if let Some(pool) = pools
+        .lock()
+        .map_err(|_| PyValueError::new_err("Arrow worker-pool cache poisoned"))?
+        .get(&workers)
+        .cloned()
+    {
+        return Ok(pool);
+    }
+
+    let pool = Arc::new(
+        ThreadPoolBuilder::new()
+            .num_threads(workers)
+            .thread_name(|index| format!("news-relevance-arrow-{index}"))
+            .build()
+            .map_err(|error| PyValueError::new_err(error.to_string()))?,
+    );
+    let mut guard = pools
+        .lock()
+        .map_err(|_| PyValueError::new_err("Arrow worker-pool cache poisoned"))?;
+    Ok(guard.entry(workers).or_insert_with(|| pool.clone()).clone())
+}
+
+enum TextColumn<'a> {
+    Utf8(&'a StringArray),
+    LargeUtf8(&'a LargeStringArray),
+}
+
+impl<'a> TextColumn<'a> {
+    #[inline(always)]
+    fn value(&self, index: usize) -> &'a str {
+        match self {
+            Self::Utf8(values) => values.value(index),
+            Self::LargeUtf8(values) => values.value(index),
+        }
+    }
+}
+
+enum TimestampColumn<'a> {
+    Second(&'a TimestampSecondArray),
+    Millisecond(&'a TimestampMillisecondArray),
+    Microsecond(&'a TimestampMicrosecondArray),
+    Nanosecond(&'a TimestampNanosecondArray),
+}
+
+impl<'a> TimestampColumn<'a> {
+    #[inline(always)]
+    fn value_microseconds(&self, index: usize) -> Result<i64, String> {
+        match self {
+            Self::Second(values) => values
+                .value(index)
+                .checked_mul(1_000_000)
+                .ok_or_else(|| "timestamp second value overflows microseconds".to_string()),
+            Self::Millisecond(values) => values
+                .value(index)
+                .checked_mul(1_000)
+                .ok_or_else(|| "timestamp millisecond value overflows microseconds".to_string()),
+            Self::Microsecond(values) => Ok(values.value(index)),
+            Self::Nanosecond(values) => Ok(values.value(index) / 1_000),
+        }
+    }
+}
+
+fn text_column(array: &dyn Array) -> Result<TextColumn<'_>, String> {
+    if array.null_count() != 0 {
+        return Err("Arrow text column must not contain nulls".to_string());
+    }
+    match array.data_type() {
+        DataType::Utf8 => Ok(TextColumn::Utf8(
+            array
+                .as_any()
+                .downcast_ref::<StringArray>()
+                .ok_or_else(|| "failed to downcast Utf8 text column".to_string())?,
+        )),
+        DataType::LargeUtf8 => Ok(TextColumn::LargeUtf8(
+            array
+                .as_any()
+                .downcast_ref::<LargeStringArray>()
+                .ok_or_else(|| "failed to downcast LargeUtf8 text column".to_string())?,
+        )),
+        other => Err(format!(
+            "Arrow text column must be Utf8 or LargeUtf8, got {other}"
+        )),
+    }
+}
+
+fn timestamp_column(array: &dyn Array) -> Result<TimestampColumn<'_>, String> {
+    if array.null_count() != 0 {
+        return Err("Arrow timestamp column must not contain nulls".to_string());
+    }
+    let (unit, timezone) = match array.data_type() {
+        DataType::Timestamp(unit, timezone) => (unit, timezone),
+        other => {
+            return Err(format!(
+                "Arrow timestamp column must be a timestamp type, got {other}"
+            ))
+        }
+    };
+    if timezone.is_none() {
+        return Err(
+            "Arrow-native fast path requires a timezone-aware timestamp column; \
+             use America/New_York (or another explicit timezone) to preserve \
+             exact effective-date semantics"
+                .to_string(),
+        );
+    }
+    match unit {
+        TimeUnit::Second => Ok(TimestampColumn::Second(
+            array
+                .as_any()
+                .downcast_ref::<TimestampSecondArray>()
+                .ok_or_else(|| "failed to downcast second timestamp column".to_string())?,
+        )),
+        TimeUnit::Millisecond => Ok(TimestampColumn::Millisecond(
+            array
+                .as_any()
+                .downcast_ref::<TimestampMillisecondArray>()
+                .ok_or_else(|| "failed to downcast millisecond timestamp column".to_string())?,
+        )),
+        TimeUnit::Microsecond => Ok(TimestampColumn::Microsecond(
+            array
+                .as_any()
+                .downcast_ref::<TimestampMicrosecondArray>()
+                .ok_or_else(|| "failed to downcast microsecond timestamp column".to_string())?,
+        )),
+        TimeUnit::Nanosecond => Ok(TimestampColumn::Nanosecond(
+            array
+                .as_any()
+                .downcast_ref::<TimestampNanosecondArray>()
+                .ok_or_else(|| "failed to downcast nanosecond timestamp column".to_string())?,
+        )),
+    }
+}
+
+fn facts_to_record_batch(rows: Vec<FactRow>) -> Result<RecordBatch, String> {
+    let mut row_index = Vec::with_capacity(rows.len());
+    let mut article_status = Vec::with_capacity(rows.len());
+    let mut sp500 = Vec::with_capacity(rows.len());
+    let mut nasdaq100 = Vec::with_capacity(rows.len());
+    let mut russell2000 = Vec::with_capacity(rows.len());
+    let mut market_wide = Vec::with_capacity(rows.len());
+    let mut observation_count = Vec::with_capacity(rows.len());
+    let mut native_candidate = Vec::with_capacity(rows.len());
+    let mut exact_candidate = Vec::with_capacity(rows.len());
+
+    for (index, article, sp, ndx, rut, market, observations, native, exact) in rows {
+        row_index.push(index as u64);
+        article_status.push(article);
+        sp500.push(sp);
+        nasdaq100.push(ndx);
+        russell2000.push(rut);
+        market_wide.push(market);
+        observation_count.push(observations as u32);
+        native_candidate.push(native);
+        exact_candidate.push(exact);
+    }
+
+    let fields = vec![
+        Field::new("row_index", DataType::UInt64, false),
+        Field::new("article_status", DataType::UInt8, false),
+        Field::new("sp500", DataType::UInt8, false),
+        Field::new("nasdaq100", DataType::UInt8, false),
+        Field::new("russell2000", DataType::UInt8, false),
+        Field::new("market_wide", DataType::UInt8, false),
+        Field::new("observation_count", DataType::UInt32, false),
+        Field::new("native_candidate", DataType::Boolean, false),
+        Field::new("exact_candidate", DataType::Boolean, false),
+    ];
+    let columns: Vec<ArrayRef> = vec![
+        Arc::new(UInt64Array::from(row_index)),
+        Arc::new(UInt8Array::from(article_status)),
+        Arc::new(UInt8Array::from(sp500)),
+        Arc::new(UInt8Array::from(nasdaq100)),
+        Arc::new(UInt8Array::from(russell2000)),
+        Arc::new(UInt8Array::from(market_wide)),
+        Arc::new(UInt32Array::from(observation_count)),
+        Arc::new(BooleanArray::from(native_candidate)),
+        Arc::new(BooleanArray::from(exact_candidate)),
+    ];
+    RecordBatch::try_new(Arc::new(Schema::new(fields)), columns).map_err(|error| error.to_string())
+}
+
+#[pyclass(frozen, module = "range_news._native")]
+struct NativeArrowCompactFactScanner {
+    inner: NativeCompactFactScanner,
+}
+
+#[pymethods]
+impl NativeArrowCompactFactScanner {
+    #[new]
+    #[pyo3(signature = (
+        patterns,
+        pattern_consumers,
+        consumers,
+        exact_specs,
+        alias_specs,
+        lexical_specs,
+        context_rules,
+        conjunction_specs
+    ))]
+    fn new(
+        patterns: Vec<String>,
+        pattern_consumers: Vec<Vec<usize>>,
+        consumers: Vec<(u8, usize, usize, usize)>,
+        exact_specs: Vec<(String, String, u8, usize)>,
+        alias_specs: Vec<(usize, i64, Option<i64>, i8, u8, bool, Option<usize>)>,
+        lexical_specs: Vec<(usize, Vec<String>, bool, bool, bool, bool)>,
+        context_rules: Vec<(usize, Vec<Vec<String>>, Vec<String>)>,
+        conjunction_specs: Vec<(usize, usize, usize, usize)>,
+    ) -> PyResult<Self> {
+        Ok(Self {
+            inner: NativeCompactFactScanner::new(
+                patterns,
+                pattern_consumers,
+                consumers,
+                exact_specs,
+                alias_specs,
+                lexical_specs,
+                context_rules,
+                conjunction_specs,
+            )?,
+        })
+    }
+
+    #[pyo3(signature = (data, text_column_name="text", timestamp_column_name="timestamp", workers=4))]
+    fn screen_arrow(
+        &self,
+        py: Python<'_>,
+        data: AnyRecordBatch,
+        text_column_name: &str,
+        timestamp_column_name: &str,
+        workers: usize,
+    ) -> PyResult<PyRecordBatch> {
+        if workers == 0 {
+            return Err(PyValueError::new_err("workers must be >= 1"));
+        }
+        let schema = data.schema()?;
+        let text_index = schema
+            .index_of(text_column_name)
+            .map_err(|error| PyValueError::new_err(error.to_string()))?;
+        let timestamp_index = schema
+            .index_of(timestamp_column_name)
+            .map_err(|error| PyValueError::new_err(error.to_string()))?;
+        let mut reader = data.into_reader()?;
+
+        let pool = worker_pool(workers)?;
+        let inner = &self.inner;
+
+        let result: Result<Vec<FactRow>, String> = py.detach(move || {
+            let mut output = Vec::new();
+            let mut row_base = 0usize;
+            for batch_result in &mut reader {
+                let batch = batch_result.map_err(|error| error.to_string())?;
+                let texts = text_column(batch.column(text_index).as_ref())?;
+                let timestamps = timestamp_column(batch.column(timestamp_index).as_ref())?;
+                let batch_rows: Result<Vec<FactRow>, String> = pool.install(|| {
+                    (0..batch.num_rows())
+                        .into_par_iter()
+                        .map_init(ScanScratch::default, |scratch, index| {
+                            let epoch = timestamps.value_microseconds(index)?;
+                            Ok(scan_one(
+                                &inner.automaton,
+                                &inner.pattern_consumers,
+                                &inner.consumers,
+                                &inner.exact_specs,
+                                &inner.aliases,
+                                &inner.lexical,
+                                &inner.contexts,
+                                &inner.conjunctions,
+                                texts.value(index),
+                                epoch,
+                                row_base + index,
+                                scratch,
+                            ))
+                        })
+                        .filter_map(|value: Result<Option<FactRow>, String>| match value {
+                            Ok(Some(row)) => Some(Ok(row)),
+                            Ok(None) => None,
+                            Err(error) => Some(Err(error)),
+                        })
+                        .collect()
+                });
+                output.extend(batch_rows?);
+                row_base += batch.num_rows();
+            }
+            output.sort_unstable_by_key(|row| row.0);
+            Ok(output)
+        });
+
+        let record_batch = facts_to_record_batch(result.map_err(PyValueError::new_err)?)
+            .map_err(PyValueError::new_err)?;
+        Ok(PyRecordBatch::new(record_batch))
+    }
+}
+
+#[pymodule]
+fn _native(module: &Bound<'_, PyModule>) -> PyResult<()> {
+    module.add_class::<NativeCompactFactScanner>()?;
+    module.add_class::<NativeArrowCompactFactScanner>()?;
+    Ok(())
+}

src/range_news/__init__.py

@@ -0,0 +1,64 @@
+"""Exact, CPU-first, traceable financial-news relevance screening."""
+
+from .api import (
+    RelevanceEngine,
+    available_backends,
+    predict,
+    predict_batch,
+    screen_arrow,
+    screen_batch,
+)
+from .customization import (
+    DefaultRanker,
+    DefaultTaxonomy,
+    GeneralEconomyTaxonomy,
+    Ranker,
+    Taxonomy,
+    TaxonomyBuilder,
+    copy_default_taxonomy,
+)
+from .models import (
+    ArrowScreeningBatch,
+    Article,
+    ArticleAdmissibilityStatus,
+    BackendInfo,
+    EvidencePath,
+    ExposureFamily,
+    ExposureRelevanceStatus,
+    Prediction,
+    PythonScreeningBatch,
+    RankedPrediction,
+    ScreeningBatch,
+    ScreeningResult,
+)
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "ArrowScreeningBatch",
+    "Article",
+    "ArticleAdmissibilityStatus",
+    "BackendInfo",
+    "DefaultRanker",
+    "DefaultTaxonomy",
+    "EvidencePath",
+    "ExposureFamily",
+    "ExposureRelevanceStatus",
+    "GeneralEconomyTaxonomy",
+    "Prediction",
+    "PythonScreeningBatch",
+    "RankedPrediction",
+    "Ranker",
+    "RelevanceEngine",
+    "ScreeningBatch",
+    "ScreeningResult",
+    "Taxonomy",
+    "TaxonomyBuilder",
+    "__version__",
+    "available_backends",
+    "copy_default_taxonomy",
+    "predict",
+    "predict_batch",
+    "screen_arrow",
+    "screen_batch",
+]

src/range_news/_core/__init__.py

@@ -0,0 +1 @@
+"""Private, deterministic financial-news relevance implementation."""

src/range_news/_core/accelerated/__init__.py

@@ -0,0 +1 @@
+"""Private high-throughput screening implementation."""

src/range_news/_core/accelerated/compact.py

@@ -0,0 +1,583 @@
+"""Compact list and Arrow screening backed by the packaged Rust extension.
+
+Rich predictions remain implemented by :class:`AcceleratedRelevanceIndicator`.
+This module owns the deliberately smaller high-throughput projection: rejected
+rows with no observations remain implicit, while only rows containing facts
+cross the Rust/Python boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from types import MappingProxyType
+
+from ..catalogs import normalize_financial_phrase
+from ..models import (
+    Article,
+    ArticleAdmissibilityStatus,
+    ExposureFamily,
+    ExposureRelevanceStatus,
+    RelevanceDecision,
+    parse_article_time,
+)
+from .indicator import AcceleratedRelevanceIndicator
+
+try:
+    from ... import _native
+except ImportError:
+    _native = None
+
+TimestampLike = datetime | str
+
+_ALIAS = 0
+_LEXICAL = 1
+_CONJUNCTION = 2
+
+_FAMILY_CODE = {
+    None: -1,
+    ExposureFamily.SP500: 0,
+    ExposureFamily.NASDAQ100: 1,
+    ExposureFamily.RUSSELL2000: 2,
+    ExposureFamily.MARKET_WIDE: 3,
+}
+_ARTICLE_STATUS = {
+    0: ArticleAdmissibilityStatus.ACCEPTED,
+    2: ArticleAdmissibilityStatus.REJECTED,
+}
+_EXPOSURE_STATUS = {
+    0: ExposureRelevanceStatus.SUPPORTED,
+    1: ExposureRelevanceStatus.PLAUSIBLE_UNRESOLVED,
+    2: ExposureRelevanceStatus.NOT_SUPPORTED,
+}
+_UNRESOLVED_TAGS = {
+    "direct_security",
+    "constituent_or_issuer",
+    "sector_or_industry",
+    "company_event",
+    "semantic_financial_other",
+}
+_EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
+
+
+def _epoch_microseconds(value: TimestampLike) -> int:
+    observed = parse_article_time(value).astimezone(timezone.utc)
+    delta = observed - _EPOCH
+    return (
+        delta.days * 86_400_000_000
+        + delta.seconds * 1_000_000
+        + delta.microseconds
+    )
+
+
+def _length(name: str, value: Sequence[object] | None, expected: int) -> None:
+    if value is not None and len(value) != expected:
+        raise ValueError(f"{name} length {len(value)} does not match {expected}")
+
+
+@dataclass(frozen=True, slots=True)
+class ScreeningResult:
+    """One compact result from materialized list screening."""
+
+    article_id: str
+    content_id: str
+    timestamp: datetime
+    article_status: ArticleAdmissibilityStatus
+    exposures: Mapping[ExposureFamily, ExposureRelevanceStatus]
+    observation_count: int = 0
+    resolution_count: int = 0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "exposures", MappingProxyType(dict(self.exposures)))
+
+    @classmethod
+    def from_decision(cls, decision: RelevanceDecision) -> "ScreeningResult":
+        return cls(
+            article_id=decision.article.article_id,
+            content_id=decision.article.content_id or decision.article.article_id,
+            timestamp=decision.article.timestamp,
+            article_status=decision.article_decision.status,
+            exposures={
+                family: decision.exposure_decisions[family].status
+                for family in ExposureFamily
+            },
+            observation_count=len(decision.observations),
+            resolution_count=len(decision.resolutions),
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        """Return a serialization-friendly row."""
+
+        return {
+            "article_id": self.article_id,
+            "content_id": self.content_id,
+            "timestamp": self.timestamp,
+            "article_status": self.article_status.value,
+            **{
+                family.value: self.exposures[family].value
+                for family in ExposureFamily
+            },
+            "observation_count": self.observation_count,
+            "resolution_count": self.resolution_count,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class ColumnArticleBatch:
+    """Storage-neutral article columns for compact list screening."""
+
+    article_ids: Sequence[str]
+    timestamps: Sequence[TimestampLike]
+    texts: Sequence[str]
+    sources: Sequence[str] | None = None
+    content_ids: Sequence[str | None] | None = None
+    decision_buckets: Sequence[str | None] | None = None
+
+    def __post_init__(self) -> None:
+        count = len(self.article_ids)
+        if len(self.timestamps) != count or len(self.texts) != count:
+            raise ValueError("article_ids, timestamps, and texts must have equal lengths")
+        _length("sources", self.sources, count)
+        _length("content_ids", self.content_ids, count)
+        _length("decision_buckets", self.decision_buckets, count)
+
+    @property
+    def count(self) -> int:
+        return len(self.article_ids)
+
+    def article(self, index: int) -> Article:
+        article_id = self.article_ids[index]
+        return Article(
+            article_id=article_id,
+            content_id=(
+                self.content_ids[index]
+                if self.content_ids is not None
+                else article_id
+            ),
+            timestamp=self.timestamps[index],
+            decision_bucket=(
+                self.decision_buckets[index]
+                if self.decision_buckets is not None
+                else None
+            ),
+            source=self.sources[index] if self.sources is not None else "unknown",
+            text=self.texts[index],
+        )
+
+    def zero_screening(self, index: int) -> ScreeningResult:
+        article_id = self.article_ids[index]
+        content_id = (
+            self.content_ids[index]
+            if self.content_ids is not None and self.content_ids[index] is not None
+            else article_id
+        )
+        return ScreeningResult(
+            article_id=article_id,
+            content_id=content_id,
+            timestamp=parse_article_time(self.timestamps[index]),
+            article_status=ArticleAdmissibilityStatus.REJECTED,
+            exposures={
+                family: ExposureRelevanceStatus.NOT_SUPPORTED
+                for family in ExposureFamily
+            },
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CompactColumnScreenBatch:
+    """Sparse list result retaining only non-default rows as Python objects."""
+
+    batch: ColumnArticleBatch
+    exception_rows: tuple[tuple[int, ScreeningResult], ...]
+    native_candidate_count: int = 0
+    exact_candidate_count: int = 0
+
+    @property
+    def count(self) -> int:
+        return self.batch.count
+
+    @property
+    def exception_count(self) -> int:
+        return len(self.exception_rows)
+
+    @property
+    def implicit_zero_count(self) -> int:
+        return self.count - self.exception_count
+
+    @property
+    def exception_indices(self) -> tuple[int, ...]:
+        return tuple(index for index, _row in self.exception_rows)
+
+    def materialize(self) -> tuple[ScreeningResult, ...]:
+        """Expand implicit default rows into a result for every input row."""
+
+        exceptions = dict(self.exception_rows)
+        return tuple(
+            exceptions.get(index) or self.batch.zero_screening(index)
+            for index in range(self.count)
+        )
+
+
+@dataclass(slots=True)
+class ArrowCompactFacts:
+    """Sparse native Arrow result keyed by the input row index."""
+
+    row_count: int | None
+    facts: object
+    _pyarrow_cache: object | None = field(default=None, init=False, repr=False)
+
+    def to_pyarrow(self):
+        """Import and cache the native result as a ``pyarrow.RecordBatch``."""
+
+        if self._pyarrow_cache is None:
+            try:
+                import pyarrow as pa
+            except ImportError as exc:
+                raise RuntimeError(
+                    "PyArrow is required to materialize Arrow screening facts"
+                ) from exc
+
+            if hasattr(self.facts, "__arrow_c_array__"):
+                self._pyarrow_cache = pa.record_batch(self.facts)
+            else:
+                method = getattr(self.facts, "into_pyarrow", None)
+                if method is None:
+                    method = getattr(self.facts, "to_pyarrow", None)
+                if method is None:
+                    raise RuntimeError(
+                        "The native Arrow result does not expose a supported "
+                        "PyArrow conversion interface"
+                    )
+                self._pyarrow_cache = method()
+        return self._pyarrow_cache
+
+    @property
+    def exception_count(self) -> int:
+        return int(self.to_pyarrow().num_rows)
+
+    @property
+    def implicit_zero_count(self) -> int:
+        if self.row_count is None:
+            raise RuntimeError("row_count is unknown for this Arrow stream")
+        return self.row_count - self.exception_count
+
+
+def _build_native_specs(indicator: AcceleratedRelevanceIndicator) -> tuple[object, ...]:
+    """Translate the loaded taxonomy into the native scanner contract."""
+
+    patterns = list(indicator._scanner.patterns)
+    pattern_ids = {pattern: index for index, pattern in enumerate(patterns)}
+    pattern_consumers: list[list[int]] = [[] for _ in patterns]
+    consumers: list[tuple[int, int, int, int]] = []
+
+    def add(pattern: str, kind: int, a: int, b: int = 0, c: int = 0) -> None:
+        consumer_id = len(consumers)
+        consumers.append((kind, a, b, c))
+        pattern_consumers[pattern_ids[pattern]].append(consumer_id)
+
+    canonical_groups = {
+        canonical_id: index
+        for index, canonical_id in enumerate(sorted(indicator.catalogs.entities))
+    }
+    context_ids = {
+        rule_id: index
+        for index, rule_id in enumerate(indicator.config.context_rules)
+    }
+
+    aliases = tuple(indicator.catalogs.aliases)
+    alias_specs = []
+    exact_specs: list[tuple[str, str, int, int]] = []
+    for alias_index, alias in enumerate(aliases):
+        entity = indicator.catalogs.entities[alias.canonical_id]
+        family = indicator.catalogs.exposure_family_for(
+            alias.canonical_id,
+            indicator.config,
+        )
+        entity_kind = (
+            0
+            if entity.entity_kind == "fund"
+            else 1
+            if entity.entity_kind == "index"
+            else 2
+        )
+        tag_type = (
+            "direct_security"
+            if entity.entity_kind == "fund"
+            else "benchmark_or_index"
+            if entity.entity_kind == "index"
+            else "constituent_or_issuer"
+        )
+        alias_specs.append(
+            (
+                canonical_groups[alias.canonical_id],
+                _epoch_microseconds(alias.valid_from),
+                (
+                    _epoch_microseconds(alias.valid_to)
+                    if alias.valid_to is not None
+                    else None
+                ),
+                _FAMILY_CODE[family],
+                entity_kind,
+                tag_type in _UNRESOLVED_TAGS,
+                (
+                    context_ids[alias.context_rule_id]
+                    if alias.requires_context and alias.context_rule_id is not None
+                    else None
+                ),
+            )
+        )
+        normalized = indicator._alias_norm.get(alias.alias_id)
+        if normalized is not None:
+            add(normalized, _ALIAS, alias_index)
+        else:
+            exact_specs.append(
+                (
+                    alias.surface,
+                    (
+                        "python_ignorecase_ascii_literal"
+                        if alias.match_mode == "exact_casefold"
+                        else "case_sensitive"
+                    ),
+                    _ALIAS,
+                    alias_index,
+                )
+            )
+
+    lexical_specs = []
+    for rule in indicator.catalogs.lexical_rules:
+        lexical_index = len(lexical_specs)
+        lexical_specs.append(
+            (
+                rule.context_window_chars,
+                [normalize_financial_phrase(term) for term in rule.context_any],
+                rule.detection_method == "event_rule",
+                rule.market_wide_authorized,
+                rule.tag_type in _UNRESOLVED_TAGS,
+                rule.event_family is not None,
+            )
+        )
+        for phrase in rule.phrases:
+            if rule.case_sensitive:
+                exact_specs.append(
+                    (phrase, "case_sensitive", _LEXICAL, lexical_index)
+                )
+            else:
+                add(
+                    indicator._lex_norm[(rule.rule_id, phrase)],
+                    _LEXICAL,
+                    lexical_index,
+                )
+
+    conjunction_specs = []
+    field_codes = {
+        "actor_phrases": 0,
+        "action_phrases": 1,
+        "object_phrases": 2,
+        "scope_phrases": 3,
+    }
+    conjunction_rules = tuple(indicator.config.market_wide_conjunctions.items())
+    for rule_index, (rule_id, rule) in enumerate(conjunction_rules):
+        conjunction_specs.append(
+            (
+                len(rule.actor_phrases),
+                len(rule.action_phrases),
+                len(rule.object_phrases),
+                len(rule.scope_phrases),
+            )
+        )
+        for field_name, field_code in field_codes.items():
+            for phrase_index, phrase in enumerate(getattr(rule, field_name)):
+                add(
+                    indicator._conj_norm[(rule_id, field_name, phrase)],
+                    _CONJUNCTION,
+                    rule_index,
+                    field_code,
+                    phrase_index,
+                )
+        for identifier in rule.actor_identifiers:
+            exact_specs.append(
+                (identifier, "case_sensitive", _CONJUNCTION, rule_index)
+            )
+
+    context_rules = [
+        (
+            rule.window_chars,
+            [
+                [normalize_financial_phrase(term) for term in clause]
+                for clause in rule.accept_any_clauses
+            ],
+            [normalize_financial_phrase(term) for term in rule.reject_any_terms],
+        )
+        for rule in indicator.config.context_rules.values()
+    ]
+
+    return (
+        patterns,
+        pattern_consumers,
+        consumers,
+        exact_specs,
+        alias_specs,
+        lexical_specs,
+        context_rules,
+        conjunction_specs,
+    )
+
+
+class CompactRelevanceIndicator(AcceleratedRelevanceIndicator):
+    """Rich exact prediction plus native compact list and Arrow projections."""
+
+    def __init__(self, config=None, catalogs=None) -> None:
+        super().__init__(config=config, catalogs=catalogs)
+        self._list_scanner = None
+        self._arrow_scanner = None
+        if _native is None:
+            return
+        has_list = hasattr(_native, "NativeCompactFactScanner")
+        has_arrow = hasattr(_native, "NativeArrowCompactFactScanner")
+        if not (has_list or has_arrow):
+            return
+        native_specs = _build_native_specs(self)
+        if has_list:
+            self._list_scanner = _native.NativeCompactFactScanner(*native_specs)
+        if has_arrow:
+            self._arrow_scanner = _native.NativeArrowCompactFactScanner(*native_specs)
+
+    @property
+    def list_available(self) -> bool:
+        return self._list_scanner is not None
+
+    @property
+    def arrow_available(self) -> bool:
+        return self.list_available and self._arrow_scanner is not None
+
+    @property
+    def matcher_backend(self) -> str:
+        if self.arrow_available:
+            return "rust_native_compact_arrow"
+        if self.list_available:
+            return "rust_native_compact"
+        return super().matcher_backend
+
+    def screen_column_batch(
+        self,
+        batch: ColumnArticleBatch,
+        *,
+        workers: int = 4,
+    ) -> CompactColumnScreenBatch:
+        """Classify list-backed columns while keeping default rows implicit."""
+
+        if isinstance(workers, bool) or not isinstance(workers, int) or workers <= 0:
+            raise ValueError("workers must be a positive integer")
+        if batch.count == 0:
+            return CompactColumnScreenBatch(batch=batch, exception_rows=())
+        if self._list_scanner is None:
+            raise RuntimeError(
+                "Compact screening requires the packaged Rust extension; "
+                "reinstall a wheel for this platform or rebuild the package"
+            )
+
+        rows = self._list_scanner.screen_facts_batch(
+            list(batch.texts),
+            [_epoch_microseconds(value) for value in batch.timestamps],
+            workers,
+        )
+        exceptions = []
+        native_candidates = 0
+        exact_candidates = 0
+        for (
+            index,
+            article_status,
+            sp500,
+            nasdaq100,
+            russell2000,
+            market_wide,
+            observation_count,
+            native_candidate,
+            exact_candidate,
+        ) in rows:
+            index = int(index)
+            native_candidates += bool(native_candidate)
+            exact_candidates += bool(exact_candidate)
+            article_id = batch.article_ids[index]
+            content_id = (
+                batch.content_ids[index]
+                if batch.content_ids is not None
+                and batch.content_ids[index] is not None
+                else article_id
+            )
+            exceptions.append(
+                (
+                    index,
+                    ScreeningResult(
+                        article_id=article_id,
+                        content_id=content_id,
+                        timestamp=parse_article_time(batch.timestamps[index]),
+                        article_status=_ARTICLE_STATUS[int(article_status)],
+                        exposures={
+                            ExposureFamily.SP500: _EXPOSURE_STATUS[int(sp500)],
+                            ExposureFamily.NASDAQ100: _EXPOSURE_STATUS[
+                                int(nasdaq100)
+                            ],
+                            ExposureFamily.RUSSELL2000: _EXPOSURE_STATUS[
+                                int(russell2000)
+                            ],
+                            ExposureFamily.MARKET_WIDE: _EXPOSURE_STATUS[
+                                int(market_wide)
+                            ],
+                        },
+                        observation_count=int(observation_count),
+                        resolution_count=int(observation_count),
+                    ),
+                )
+            )
+
+        return CompactColumnScreenBatch(
+            batch=batch,
+            exception_rows=tuple(exceptions),
+            native_candidate_count=native_candidates,
+            exact_candidate_count=exact_candidates,
+        )
+
+    def screen_arrow(
+        self,
+        data,
+        *,
+        text_column: str = "text",
+        timestamp_column: str = "timestamp",
+        workers: int = 4,
+        row_count: int | None = None,
+    ) -> ArrowCompactFacts:
+        """Screen an Arrow batch or stream through its PyCapsule interface."""
+
+        if isinstance(workers, bool) or not isinstance(workers, int) or workers <= 0:
+            raise ValueError("workers must be a positive integer")
+        if self._arrow_scanner is None:
+            raise RuntimeError("The packaged Arrow screening extension is unavailable")
+        if row_count is None:
+            discovered = getattr(data, "num_rows", None)
+            if discovered is not None:
+                row_count = int(discovered)
+        elif (
+            isinstance(row_count, bool)
+            or not isinstance(row_count, int)
+            or row_count < 0
+        ):
+            raise ValueError("row_count must be a non-negative integer or None")
+
+        facts = self._arrow_scanner.screen_arrow(
+            data,
+            text_column,
+            timestamp_column,
+            workers,
+        )
+        return ArrowCompactFacts(row_count=row_count, facts=facts)
+
+
+__all__ = [
+    "ArrowCompactFacts",
+    "ColumnArticleBatch",
+    "CompactColumnScreenBatch",
+    "CompactRelevanceIndicator",
+    "ScreeningResult",
+]

src/range_news/_core/accelerated/indicator.py

@@ -0,0 +1,384 @@
+"""Isolated accelerated matcher for the frozen news-relevance implementation.
+
+The public decision logic remains in ``RelevanceIndicator``. This subclass only
+replaces ``observe()`` so normalized text is built once per article and all
+normalized phrases share one multi-pattern scan. Exact/context semantics and
+all downstream resolution/evidence/decision code stay in the existing package.
+"""
+from __future__ import annotations
+
+import os
+import re
+from collections import defaultdict
+from collections.abc import Iterable, Sequence
+from concurrent.futures import ThreadPoolExecutor
+
+from ..catalogs import (
+    CatalogAlias,
+    _TOKEN_CHARS,
+    _TOKEN_PATTERN_CHARS,
+    _normalize_with_offsets,
+    context_result,
+    find_normalized_phrase_spans,
+    normalize_financial_phrase,
+)
+from ..indicator import RelevanceIndicator, _method_for, _stable_id
+from ..models import Article, Observation, ObservationBundle, RelevanceDecision
+
+try:
+    from ahocorasick_rs import AhoCorasick, Implementation
+except ImportError:  # optional accelerator
+    AhoCorasick = None
+    Implementation = None
+
+Span = tuple[int, int]
+
+
+class _Scanner:
+    def __init__(self, patterns: Iterable[str]) -> None:
+        self.patterns = tuple(sorted({p for p in patterns if p}))
+        self.automaton = None
+        if AhoCorasick is not None and self.patterns:
+            self.automaton = AhoCorasick(
+                self.patterns,
+                implementation=Implementation.DFA,
+                store_patterns=False,
+            )
+
+    @property
+    def backend(self) -> str:
+        return "rust_aho_corasick_dfa" if self.automaton is not None else "python_find"
+
+    @staticmethod
+    def _boundary(text: str, start: int, end: int) -> bool:
+        return (
+            (start == 0 or text[start - 1] not in _TOKEN_CHARS)
+            and (end == len(text) or text[end] not in _TOKEN_CHARS)
+        )
+
+    def scan(self, text: str) -> dict[str, tuple[Span, ...]]:
+        normalized, offsets = _normalize_with_offsets(text)
+        if not normalized:
+            return {}
+        hits: dict[int, list[Span]] = defaultdict(list)
+        if self.automaton is not None:
+            matches = self.automaton.find_matches_as_indexes(normalized, overlapping=True)
+            for pid, start, end in matches:
+                if self._boundary(normalized, start, end):
+                    hits[int(pid)].append((start, end))
+        else:
+            for pid, pattern in enumerate(self.patterns):
+                cursor = 0
+                while True:
+                    start = normalized.find(pattern, cursor)
+                    if start < 0:
+                        break
+                    end = start + len(pattern)
+                    if self._boundary(normalized, start, end):
+                        hits[pid].append((start, end))
+                    cursor = start + 1
+        return {
+            self.patterns[pid]: tuple(
+                (offsets[s], offsets[e - 1] + 1) for s, e in spans
+            )
+            for pid, spans in hits.items()
+        }
+
+
+class AcceleratedRelevanceIndicator(RelevanceIndicator):
+    """Drop-in indicator that preserves outputs while eliminating repeated normalization."""
+
+    def __init__(self, config=None, catalogs=None) -> None:
+        super().__init__(config=config, catalogs=catalogs)
+        patterns: set[str] = set()
+        self._alias_norm: dict[str, str] = {}
+        self._alias_regex: dict[str, re.Pattern[str]] = {}
+        for alias in self.catalogs.aliases:
+            if alias.match_mode == "normalized_phrase":
+                key = normalize_financial_phrase(alias.surface)
+                self._alias_norm[alias.alias_id] = key
+                patterns.add(key)
+            else:
+                flags = (
+                    0
+                    if alias.match_mode in {"exact_identifier", "exact_case_sensitive"}
+                    else re.IGNORECASE
+                )
+                self._alias_regex[alias.alias_id] = re.compile(
+                    rf"(?<![{_TOKEN_PATTERN_CHARS}])"
+                    rf"{re.escape(alias.surface)}"
+                    rf"(?![{_TOKEN_PATTERN_CHARS}])",
+                    flags,
+                )
+
+        self._lex_norm: dict[tuple[str, str], str] = {}
+        self._lex_regex: dict[tuple[str, str], re.Pattern[str]] = {}
+        for rule in self.catalogs.lexical_rules:
+            for phrase in rule.phrases:
+                key = (rule.rule_id, phrase)
+                if rule.case_sensitive:
+                    self._lex_regex[key] = re.compile(
+                        rf"(?<![{_TOKEN_PATTERN_CHARS}])"
+                        rf"{re.escape(phrase)}"
+                        rf"(?![{_TOKEN_PATTERN_CHARS}])"
+                    )
+                else:
+                    value = normalize_financial_phrase(phrase)
+                    self._lex_norm[key] = value
+                    patterns.add(value)
+
+        self._conj_norm: dict[tuple[str, str, str], str] = {}
+        self._conj_regex: dict[tuple[str, str], re.Pattern[str]] = {}
+        for rule_id, rule in self.config.market_wide_conjunctions.items():
+            for field in (
+                "actor_phrases",
+                "action_phrases",
+                "object_phrases",
+                "scope_phrases",
+            ):
+                for phrase in getattr(rule, field):
+                    value = normalize_financial_phrase(phrase)
+                    self._conj_norm[(rule_id, field, phrase)] = value
+                    patterns.add(value)
+            for identifier in rule.actor_identifiers:
+                self._conj_regex[(rule_id, identifier)] = re.compile(
+                    rf"(?<![A-Za-z0-9_]){re.escape(identifier)}(?![A-Za-z0-9_])"
+                )
+        self._scanner = _Scanner(patterns)
+
+    @property
+    def matcher_backend(self) -> str:
+        return self._scanner.backend
+
+    def _alias_spans(
+        self,
+        alias: CatalogAlias,
+        text: str,
+        hits: dict[str, tuple[Span, ...]],
+    ) -> tuple[Span, ...]:
+        normalized = self._alias_norm.get(alias.alias_id)
+        if normalized is not None:
+            return hits.get(normalized, ())
+        return tuple(
+            (m.start(), m.end())
+            for m in self._alias_regex[alias.alias_id].finditer(text)
+        )
+
+    def observe(self, article: Article) -> ObservationBundle:
+        text = article.text
+        hits = self._scanner.scan(text)
+        observations: list[Observation] = []
+        candidates: list[tuple[CatalogAlias, int, int]] = []
+        for alias in self.catalogs.aliases:
+            candidates.extend(
+                (alias, s, e)
+                for s, e in self._alias_spans(alias, text, hits)
+            )
+
+        longest: dict[tuple[str, int], int] = {}
+        for alias, start, end in candidates:
+            key = (alias.canonical_id, start)
+            longest[key] = max(longest.get(key, 0), end)
+
+        for alias, start, end in candidates:
+            if end < longest[(alias.canonical_id, start)]:
+                continue
+            entity = self.catalogs.entities[alias.canonical_id]
+            reason = "context_not_required"
+            if alias.requires_context:
+                _, reason = context_result(
+                    text,
+                    start=start,
+                    end=end,
+                    rule=self.config.context_rules.get(alias.context_rule_id or ""),
+                )
+            observations.append(
+                Observation(
+                    observation_id=_stable_id(
+                        "obs2",
+                        article.article_id,
+                        start,
+                        end,
+                        entity.entity_concept,
+                        _method_for(alias),
+                        alias.alias_id,
+                    ),
+                    article_id=article.article_id,
+                    matched_surface=text[start:end],
+                    span_start=start,
+                    span_end=end,
+                    entity_concept=entity.entity_concept,
+                    detection_method=_method_for(alias),
+                    confidence=1.0,
+                    candidate_canonical_id=alias.canonical_id,
+                    catalog_entry_id=alias.alias_id,
+                    catalog_version=self.catalogs.entity_catalog_version,
+                    tag_type=(
+                        "direct_security"
+                        if entity.entity_kind == "fund"
+                        else (
+                            "benchmark_or_index"
+                            if entity.entity_kind == "index"
+                            else "constituent_or_issuer"
+                        )
+                    ),
+                    context_status=reason,
+                    source_id=alias.source_id,
+                )
+            )
+
+        for rule in self.catalogs.lexical_rules:
+            for phrase in rule.phrases:
+                key = (rule.rule_id, phrase)
+                spans = (
+                    tuple(
+                        (m.start(), m.end())
+                        for m in self._lex_regex[key].finditer(text)
+                    )
+                    if rule.case_sensitive
+                    else hits.get(self._lex_norm[key], ())
+                )
+                for start, end in spans:
+                    context_ok = True
+                    if rule.context_any:
+                        window = text[
+                            max(0, start - rule.context_window_chars) : min(
+                                len(text), end + rule.context_window_chars
+                            )
+                        ]
+                        context_ok = any(
+                            bool(find_normalized_phrase_spans(window, term))
+                            for term in rule.context_any
+                        )
+                    method = rule.detection_method
+                    stable = (
+                        (article.article_id, start, end, rule.rule_id)
+                        if method == "event_rule"
+                        else (
+                            article.article_id,
+                            start,
+                            end,
+                            rule.entity_concept,
+                            method,
+                            self.catalogs.lexical_catalog_version,
+                        )
+                    )
+                    observations.append(
+                        Observation(
+                            observation_id=_stable_id(
+                                "signal2" if method == "event_rule" else "obs2",
+                                *stable,
+                            ),
+                            article_id=article.article_id,
+                            matched_surface=text[start:end],
+                            span_start=start,
+                            span_end=end,
+                            entity_concept=rule.entity_concept,
+                            detection_method=method,
+                            confidence=1.0,
+                            candidate_canonical_id=rule.target_id,
+                            catalog_version=self.catalogs.lexical_catalog_version,
+                            rule_id=rule.rule_id,
+                            tag_type=rule.tag_type,
+                            event_family=rule.event_family,
+                            market_wide_authorized=rule.market_wide_authorized,
+                            context_status=(
+                                "lexical_context_satisfied"
+                                if context_ok
+                                else "lexical_context_not_satisfied"
+                            ),
+                            source_id=rule.source_id,
+                        )
+                    )
+
+        for rule_id, rule in self.config.market_wide_conjunctions.items():
+            def spans(field: str) -> list[Span]:
+                return [
+                    span
+                    for phrase in getattr(rule, field)
+                    for span in hits.get(
+                        self._conj_norm[(rule_id, field, phrase)], ()
+                    )
+                ]
+
+            actor = spans("actor_phrases")
+            actor.extend(
+                (m.start(), m.end())
+                for identifier in rule.actor_identifiers
+                for m in self._conj_regex[(rule_id, identifier)].finditer(text)
+            )
+            action = spans("action_phrases")
+            obj = spans("object_phrases")
+            scope = spans("scope_phrases")
+            if not all((actor, action, obj, scope)):
+                continue
+            contributing = [actor[0], action[0], obj[0], scope[0]]
+            start = min(s for s, _ in contributing)
+            end = max(e for _, e in contributing)
+            observations.append(
+                Observation(
+                    observation_id=_stable_id(
+                        "signal2", article.article_id, start, end, rule_id
+                    ),
+                    article_id=article.article_id,
+                    matched_surface=text[start:end],
+                    span_start=start,
+                    span_end=end,
+                    entity_concept=rule.entity_concept,
+                    detection_method="event_rule",
+                    confidence=1.0,
+                    candidate_canonical_id=rule.target_id,
+                    catalog_version=self.config.version,
+                    rule_id=rule_id,
+                    tag_type=rule.tag_type,
+                    event_family=rule.event_family,
+                    market_wide_authorized=True,
+                    context_status="market_wide_conjunction_satisfied",
+                    source_id="sec_rules_regulations",
+                )
+            )
+
+        return ObservationBundle(
+            article=article,
+            observations=tuple(
+                sorted(set(observations), key=lambda row: row.observation_id)
+            ),
+        )
+
+    def predict_batch(
+        self,
+        articles: Sequence[Article],
+        *,
+        workers: int = 1,
+    ) -> tuple[RelevanceDecision, ...]:
+        """Predict an ordered batch. ``workers=1`` is the lowest-overhead default."""
+        if isinstance(workers, bool) or not isinstance(workers, int) or workers <= 0:
+            raise ValueError("workers must be a positive integer")
+        if workers == 1 or len(articles) <= 1:
+            return tuple(self.predict(article) for article in articles)
+        count = min(workers, len(articles), os.cpu_count() or 1)
+        with ThreadPoolExecutor(max_workers=count) as pool:
+            return tuple(pool.map(self.predict, articles))
+
+
+def assert_decisions_equivalent(
+    baseline: Sequence[RelevanceDecision],
+    accelerated: Sequence[RelevanceDecision],
+) -> None:
+    """Require exact observations, resolutions, article decisions, and exposures."""
+    if len(baseline) != len(accelerated):
+        raise AssertionError(
+            f"decision count differs: {len(baseline)} != {len(accelerated)}"
+        )
+    for i, (left, right) in enumerate(zip(baseline, accelerated, strict=True)):
+        article_id = left.article.article_id
+        if left.article != right.article:
+            raise AssertionError(f"article differs at {i}: {article_id}")
+        if left.observations != right.observations:
+            raise AssertionError(f"observations differ at {i}: {article_id}")
+        if left.resolutions != right.resolutions:
+            raise AssertionError(f"resolutions differ at {i}: {article_id}")
+        if left.article_decision != right.article_decision:
+            raise AssertionError(f"article decision differs at {i}: {article_id}")
+        if dict(left.exposure_decisions) != dict(right.exposure_decisions):
+            raise AssertionError(f"exposure decisions differ at {i}: {article_id}")

src/range_news/_core/catalogs.py

@@ -0,0 +1,470 @@
+"""Catalog loading, conservative matching, and effective-date utilities."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+import yaml
+
+from .config import ContextRule, NewsRelevanceConfig
+from .models import ExposureFamily, parse_article_time
+
+_DASHES = {"-", "‐", "‑", "‒", "–", "—", "―", "−"}
+_APOSTROPHES = {"'", "’", "‘", "‛", "`", "´"}
+_SEPARATOR_PUNCTUATION = set(".,:;()[]{}／/")
+_TOKEN_CHARS = set("abcdefghijklmnopqrstuvwxyz0123456789_")
+_TOKEN_PATTERN_CHARS = r"A-Za-z0-9_"
+
+
+def _as_utc(value: datetime | str) -> datetime:
+    return parse_article_time(value).astimezone(timezone.utc)
+
+
+def active_during(
+    timestamp: datetime | str,
+    *,
+    valid_from: datetime | str,
+    valid_to: datetime | str | None = None,
+) -> bool:
+    """Return whether a timestamp belongs to the interval ``[from, to)``."""
+
+    start = _as_utc(valid_from)
+    end = _as_utc(valid_to) if valid_to is not None else None
+    if end is not None and start >= end:
+        raise ValueError("valid_to must be later than valid_from")
+    observed = _as_utc(timestamp)
+    return start <= observed and (end is None or observed < end)
+
+
+def _normalize_with_offsets(value: str) -> tuple[str, list[int]]:
+    characters: list[str] = []
+    offsets: list[int] = []
+    pending_space = False
+    for source_index, source_character in enumerate(value):
+        for character in unicodedata.normalize("NFKC", source_character).casefold():
+            if character in _DASHES or character in _SEPARATOR_PUNCTUATION:
+                character = " "
+            elif character in _APOSTROPHES:
+                character = "'"
+            if character.isspace():
+                pending_space = bool(characters)
+                continue
+            if pending_space:
+                characters.append(" ")
+                offsets.append(source_index)
+                pending_space = False
+            characters.append(character)
+            offsets.append(source_index)
+    return "".join(characters), offsets
+
+
+def normalize_financial_phrase(value: str) -> str:
+    """Normalize without stemming, fuzzy edits, token deletion, or correction."""
+
+    return _normalize_with_offsets(value)[0]
+
+
+def find_normalized_phrase_spans(text: str, phrase: str) -> list[tuple[int, int]]:
+    normalized_text, offsets = _normalize_with_offsets(text)
+    normalized_phrase = normalize_financial_phrase(phrase)
+    if not normalized_phrase or not offsets:
+        return []
+    spans: list[tuple[int, int]] = []
+    cursor = 0
+    while True:
+        start = normalized_text.find(normalized_phrase, cursor)
+        if start < 0:
+            break
+        end = start + len(normalized_phrase)
+        left_ok = start == 0 or normalized_text[start - 1] not in _TOKEN_CHARS
+        right_ok = (
+            end == len(normalized_text) or normalized_text[end] not in _TOKEN_CHARS
+        )
+        if left_ok and right_ok:
+            spans.append((offsets[start], offsets[end - 1] + 1))
+        cursor = start + 1
+    return spans
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogEntity:
+    canonical_id: str
+    canonical_name: str
+    entity_concept: str
+    entity_kind: str
+    valid_from: str
+    valid_to: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogAlias:
+    alias_id: str
+    canonical_id: str
+    surface: str
+    match_mode: str
+    requires_context: bool
+    context_rule_id: str | None
+    valid_from: str
+    valid_to: str | None
+    source_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogRelationship:
+    relationship_id: str
+    relationship_type: str
+    subject_id: str
+    object_id: str
+    valid_from: str
+    valid_to: str | None
+    catalog_version: str
+
+
+@dataclass(frozen=True, slots=True)
+class LexicalRule:
+    rule_id: str
+    entity_concept: str
+    tag_type: str
+    target_id: str | None
+    phrases: tuple[str, ...]
+    detection_method: str
+    market_wide_authorized: bool
+    case_sensitive: bool
+    context_window_chars: int
+    context_any: tuple[str, ...]
+    event_family: str | None
+    source_id: str
+
+
+@dataclass(frozen=True, slots=True)
+class CatalogBundle:
+    entity_catalog_version: str
+    lexical_catalog_version: str
+    entities: Mapping[str, CatalogEntity]
+    aliases: tuple[CatalogAlias, ...]
+    relationships: Mapping[str, CatalogRelationship]
+    lexical_rules: tuple[LexicalRule, ...]
+
+    def exposure_family_for(
+        self, canonical_id: str, config: NewsRelevanceConfig
+    ) -> ExposureFamily | None:
+        families = [
+            family
+            for family, members in config.exposure_members.items()
+            if canonical_id in members
+        ]
+        if len(families) > 1:
+            raise ValueError(
+                f"canonical ID {canonical_id!r} belongs to multiple families"
+            )
+        return families[0] if families else None
+
+    def active_relationship_path(
+        self,
+        canonical_id: str,
+        timestamp: datetime | str,
+        config: NewsRelevanceConfig,
+    ) -> tuple[str, ...]:
+        path = config.relationship_paths.get(canonical_id, ())
+        current = canonical_id
+        for relationship_id in path:
+            relationship = self.relationships.get(relationship_id)
+            if relationship is None or relationship.subject_id != current:
+                return ()
+            if not active_during(
+                timestamp,
+                valid_from=relationship.valid_from,
+                valid_to=relationship.valid_to,
+            ):
+                return ()
+            current = relationship.object_id
+        family = self.exposure_family_for(canonical_id, config)
+        if (
+            path
+            and family is not None
+            and current not in config.exposure_members[family]
+        ):
+            return ()
+        return tuple(path)
+
+
+def _read_yaml(path: Path) -> Mapping[str, Any]:
+    with path.open(encoding="utf-8") as handle:
+        value = yaml.safe_load(handle)
+    if not isinstance(value, Mapping):
+        raise TypeError(f"YAML root must be a mapping: {path}")
+    return value
+
+
+def _exact_keys(value: Mapping[str, Any], allowed: set[str], name: str) -> None:
+    unknown = set(value) - allowed
+    if unknown:
+        raise ValueError(f"unknown {name} keys: {sorted(unknown)}")
+
+
+def load_catalogs(config: NewsRelevanceConfig) -> CatalogBundle:
+    entity_root = _read_yaml(config.entity_catalog_path)
+    lexical_root = _read_yaml(config.lexical_catalog_path)
+    _exact_keys(
+        entity_root,
+        {
+            "catalog_version",
+            "source_as_of",
+            "constituent_evidence_enabled",
+            "entities",
+            "aliases",
+            "context_rules",
+            "relationships",
+        },
+        "entity catalog",
+    )
+    _exact_keys(
+        lexical_root,
+        {"catalog_version", "source_as_of", "normalization_version", "rules"},
+        "lexical catalog",
+    )
+    if entity_root.get("constituent_evidence_enabled") is not False:
+        raise ValueError("entity catalog must fail closed on constituent evidence")
+    entity_version = str(entity_root.get("catalog_version", ""))
+    lexical_version = str(lexical_root.get("catalog_version", ""))
+    if not entity_version or not lexical_version:
+        raise ValueError("catalog versions must be non-empty")
+
+    entities: dict[str, CatalogEntity] = {}
+    for raw in entity_root.get("entities", ()):
+        _exact_keys(
+            raw,
+            {
+                "canonical_id",
+                "canonical_name",
+                "entity_concept",
+                "entity_kind",
+                "valid_from",
+                "valid_to",
+            },
+            "entity record",
+        )
+        entity = CatalogEntity(
+            canonical_id=str(raw["canonical_id"]),
+            canonical_name=str(raw["canonical_name"]),
+            entity_concept=str(raw["entity_concept"]),
+            entity_kind=str(raw["entity_kind"]),
+            valid_from=str(raw["valid_from"]),
+            valid_to=str(raw["valid_to"]) if raw.get("valid_to") is not None else None,
+        )
+        if entity.canonical_id in entities:
+            raise ValueError(f"duplicate entity {entity.canonical_id}")
+        active_during(
+            entity.valid_from, valid_from=entity.valid_from, valid_to=entity.valid_to
+        )
+        entities[entity.canonical_id] = entity
+
+    aliases: list[CatalogAlias] = []
+    seen_aliases: set[str] = set()
+    for raw in entity_root.get("aliases", ()):
+        _exact_keys(
+            raw,
+            {
+                "alias_id",
+                "canonical_id",
+                "surface",
+                "match_mode",
+                "requires_context",
+                "context_rule_id",
+                "valid_from",
+                "valid_to",
+                "source_id",
+                "source_url",
+            },
+            "alias record",
+        )
+        canonical_id = str(raw["canonical_id"])
+        entity = entities.get(canonical_id)
+        if entity is None:
+            raise ValueError(f"alias references unknown entity {canonical_id}")
+        alias_id = str(raw["alias_id"])
+        if alias_id in seen_aliases:
+            raise ValueError(f"duplicate alias {alias_id}")
+        seen_aliases.add(alias_id)
+        override = config.alias_policy_overrides.get(alias_id, {})
+        requires_context = bool(
+            override.get("context_required", raw.get("requires_context", False))
+        )
+        context_rule_id = override.get("context_rule_id", raw.get("context_rule_id"))
+        if requires_context and str(context_rule_id) not in config.context_rules:
+            raise ValueError(f"alias {alias_id} references an unknown context rule")
+        alias = CatalogAlias(
+            alias_id=alias_id,
+            canonical_id=canonical_id,
+            surface=str(raw["surface"]),
+            match_mode=str(raw["match_mode"]),
+            requires_context=requires_context,
+            context_rule_id=str(context_rule_id) if context_rule_id else None,
+            valid_from=str(raw.get("valid_from", entity.valid_from)),
+            valid_to=(
+                str(raw["valid_to"])
+                if raw.get("valid_to") is not None
+                else entity.valid_to
+            ),
+            source_id=str(raw["source_id"]),
+        )
+        if alias.match_mode not in {
+            "exact_identifier",
+            "exact_case_sensitive",
+            "exact_casefold",
+            "normalized_phrase",
+        }:
+            raise ValueError(f"unsupported match mode {alias.match_mode}")
+        aliases.append(alias)
+
+    relationships: dict[str, CatalogRelationship] = {}
+    for raw in entity_root.get("relationships", ()):
+        _exact_keys(
+            raw,
+            {
+                "relationship_id",
+                "relationship_type",
+                "subject_id",
+                "object_id",
+                "valid_from",
+                "valid_to",
+                "source_id",
+                "source_url",
+            },
+            "relationship record",
+        )
+        relationship = CatalogRelationship(
+            relationship_id=str(raw["relationship_id"]),
+            relationship_type=str(raw["relationship_type"]),
+            subject_id=str(raw["subject_id"]),
+            object_id=str(raw["object_id"]),
+            valid_from=str(raw["valid_from"]),
+            valid_to=str(raw["valid_to"]) if raw.get("valid_to") is not None else None,
+            catalog_version=entity_version,
+        )
+        if relationship.relationship_id in relationships:
+            raise ValueError(f"duplicate relationship {relationship.relationship_id}")
+        if (
+            relationship.subject_id not in entities
+            or relationship.object_id not in entities
+        ):
+            raise ValueError("relationship endpoint is missing from the catalog")
+        active_during(
+            relationship.valid_from,
+            valid_from=relationship.valid_from,
+            valid_to=relationship.valid_to,
+        )
+        relationships[relationship.relationship_id] = relationship
+
+    for path in config.relationship_paths.values():
+        if any(relationship_id not in relationships for relationship_id in path):
+            raise ValueError("configured relationship path references an unknown row")
+
+    lexical_rules: list[LexicalRule] = []
+    seen_rules: set[str] = set()
+    for raw in lexical_root.get("rules", ()):
+        _exact_keys(
+            raw,
+            {
+                "rule_id",
+                "entity_concept",
+                "tag_type",
+                "target_id",
+                "market_wide_authorized",
+                "phrases",
+                "source_id",
+                "source_url",
+                "case_sensitive",
+                "context_window_chars",
+                "context_any",
+                "detection_method",
+                "event_family",
+            },
+            "lexical rule",
+        )
+        rule_id = str(raw["rule_id"])
+        if rule_id in seen_rules:
+            raise ValueError(f"duplicate lexical rule {rule_id}")
+        seen_rules.add(rule_id)
+        rule = LexicalRule(
+            rule_id=rule_id,
+            entity_concept=str(raw["entity_concept"]),
+            tag_type=str(raw["tag_type"]),
+            target_id=(
+                str(raw["target_id"]) if raw.get("target_id") is not None else None
+            ),
+            phrases=tuple(str(item) for item in raw["phrases"]),
+            detection_method=str(raw.get("detection_method", "lexical_phrase")),
+            market_wide_authorized=raw.get("market_wide_authorized") is True,
+            case_sensitive=raw.get("case_sensitive") is True,
+            context_window_chars=int(raw.get("context_window_chars", 0)),
+            context_any=tuple(str(item) for item in raw.get("context_any", ())),
+            event_family=(
+                str(raw["event_family"])
+                if raw.get("event_family") is not None
+                else None
+            ),
+            source_id=str(raw["source_id"]),
+        )
+        if rule.tag_type not in config.ranking_tiers:
+            raise ValueError(f"lexical tag type {rule.tag_type!r} has no ranking tier")
+        lexical_rules.append(rule)
+
+    return CatalogBundle(
+        entity_catalog_version=entity_version,
+        lexical_catalog_version=lexical_version,
+        entities=MappingProxyType(entities),
+        aliases=tuple(aliases),
+        relationships=MappingProxyType(relationships),
+        lexical_rules=tuple(lexical_rules),
+    )
+
+
+def alias_spans(text: str, alias: CatalogAlias) -> list[tuple[int, int]]:
+    if alias.match_mode == "normalized_phrase":
+        return find_normalized_phrase_spans(text, alias.surface)
+    flags = (
+        0
+        if alias.match_mode in {"exact_identifier", "exact_case_sensitive"}
+        else re.IGNORECASE
+    )
+    pattern = re.compile(
+        rf"(?<![{_TOKEN_PATTERN_CHARS}]){re.escape(alias.surface)}(?![{_TOKEN_PATTERN_CHARS}])",
+        flags,
+    )
+    return [(match.start(), match.end()) for match in pattern.finditer(text)]
+
+
+def lexical_spans(text: str, rule: LexicalRule, phrase: str) -> list[tuple[int, int]]:
+    if rule.case_sensitive:
+        pattern = re.compile(
+            rf"(?<![{_TOKEN_PATTERN_CHARS}]){re.escape(phrase)}(?![{_TOKEN_PATTERN_CHARS}])"
+        )
+        return [(match.start(), match.end()) for match in pattern.finditer(text)]
+    return find_normalized_phrase_spans(text, phrase)
+
+
+def context_result(
+    text: str, *, start: int, end: int, rule: ContextRule | None
+) -> tuple[bool, str]:
+    if rule is None:
+        return False, "missing_context_rule"
+    window = text[
+        max(0, start - rule.window_chars) : min(len(text), end + rule.window_chars)
+    ]
+    for term in rule.reject_any_terms:
+        if find_normalized_phrase_spans(window, term):
+            return False, "explicit_collision_exclusion"
+    for clause in rule.accept_any_clauses:
+        if clause and all(
+            find_normalized_phrase_spans(window, term) for term in clause
+        ):
+            return True, "context_clause_satisfied"
+    return False, "context_clause_not_satisfied"

src/range_news/_core/catalogs/entities.yml

@@ -0,0 +1,186 @@
+catalog_version: "relevance-general-economy-entities-2026-09-01-v1"
+source_as_of: "2026-09-01"
+constituent_evidence_enabled: false
+
+entities:
+  - canonical_id: SPY
+    canonical_name: "SPDR S&P 500 ETF Trust"
+    entity_concept: investment_fund
+    entity_kind: fund
+    valid_from: "1993-01-22 00:00:00-05:00"
+    valid_to: null
+  - canonical_id: QQQ
+    canonical_name: "Invesco QQQ"
+    entity_concept: investment_fund
+    entity_kind: fund
+    valid_from: "1999-03-10 00:00:00-05:00"
+    valid_to: null
+  - canonical_id: IWM
+    canonical_name: "iShares Russell 2000 ETF"
+    entity_concept: investment_fund
+    entity_kind: fund
+    valid_from: "2000-05-22 00:00:00-04:00"
+    valid_to: null
+  - canonical_id: "INDEX:SP500"
+    canonical_name: "S&P 500"
+    entity_concept: market_index
+    entity_kind: index
+    valid_from: "1957-03-04 00:00:00-05:00"
+    valid_to: null
+  - canonical_id: "INDEX:NASDAQ100"
+    canonical_name: "Nasdaq-100 Index"
+    entity_concept: market_index
+    entity_kind: index
+    valid_from: "1985-01-31 00:00:00-05:00"
+    valid_to: null
+  - canonical_id: "INDEX:RUSSELL2000"
+    canonical_name: "Russell 2000 Index"
+    entity_concept: market_index
+    entity_kind: index
+    valid_from: "1984-01-01 00:00:00-05:00"
+    valid_to: null
+
+aliases:
+  - alias_id: ticker-SPY
+    canonical_id: SPY
+    surface: SPY
+    match_mode: exact_case_sensitive
+    requires_context: true
+    context_rule_id: ticker-collision-SPY-v1
+    source_id: ssga-spy
+    source_url: "https://www.ssga.com/us/en/intermediary/etfs/spdr-sp-500-etf-trust-spy"
+  - alias_id: name-SPY
+    canonical_id: SPY
+    surface: "SPDR S&P 500 ETF Trust"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: ssga-spy
+    source_url: "https://www.ssga.com/us/en/intermediary/etfs/spdr-sp-500-etf-trust-spy"
+  - alias_id: name-SPY-short
+    canonical_id: SPY
+    surface: "SPDR S&P 500 ETF"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: ssga-spy
+    source_url: "https://www.ssga.com/us/en/intermediary/etfs/spdr-sp-500-etf-trust-spy"
+
+  - alias_id: ticker-QQQ
+    canonical_id: QQQ
+    surface: QQQ
+    match_mode: exact_identifier
+    requires_context: false
+    source_id: invesco-qqq
+    source_url: "https://www.invesco.com/qqq-etf/en/home.html"
+  - alias_id: name-QQQ-current
+    canonical_id: QQQ
+    surface: "Invesco QQQ"
+    match_mode: normalized_phrase
+    requires_context: false
+    valid_from: "2018-06-04 00:00:00-04:00"
+    valid_to: null
+    source_id: invesco-qqq
+    source_url: "https://www.invesco.com/qqq-etf/en/home.html"
+  - alias_id: name-QQQ-current-etf
+    canonical_id: QQQ
+    surface: "Invesco QQQ ETF"
+    match_mode: normalized_phrase
+    requires_context: false
+    valid_from: "2018-06-04 00:00:00-04:00"
+    valid_to: null
+    source_id: invesco-qqq
+    source_url: "https://www.invesco.com/qqq-etf/en/home.html"
+  - alias_id: name-QQQ-historical
+    canonical_id: QQQ
+    surface: "PowerShares QQQ Trust, Series 1"
+    match_mode: normalized_phrase
+    requires_context: false
+    valid_from: "1999-03-10 00:00:00-05:00"
+    valid_to: "2018-06-04 00:00:00-04:00"
+    source_id: sec-qqq-historical
+    source_url: "https://www.sec.gov/Archives/edgar/data/1067839/000119312518023862/d423471d485bpos.htm"
+
+  - alias_id: ticker-IWM
+    canonical_id: IWM
+    surface: IWM
+    match_mode: exact_identifier
+    requires_context: false
+    source_id: ishares-iwm
+    source_url: "https://www.ishares.com/us/products/239710/ishares-russell-2000-etf"
+  - alias_id: name-IWM
+    canonical_id: IWM
+    surface: "iShares Russell 2000 ETF"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: ishares-iwm
+    source_url: "https://www.ishares.com/us/products/239710/ishares-russell-2000-etf"
+
+  - alias_id: index-SP500
+    canonical_id: "INDEX:SP500"
+    surface: "S&P 500"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: sp-global-sp500
+    source_url: "https://www.spglobal.com/spdji/en/indices/equity/sp-500/"
+  - alias_id: index-SP500-name
+    canonical_id: "INDEX:SP500"
+    surface: "S&P 500 Index"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: sp-global-sp500
+    source_url: "https://www.spglobal.com/spdji/en/indices/equity/sp-500/"
+  - alias_id: index-NASDAQ100
+    canonical_id: "INDEX:NASDAQ100"
+    surface: "Nasdaq-100"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: nasdaq-100
+    source_url: "https://indexes.nasdaqomx.com/Index/Overview/NDX"
+  - alias_id: index-NASDAQ100-space
+    canonical_id: "INDEX:NASDAQ100"
+    surface: "Nasdaq 100"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: nasdaq-100
+    source_url: "https://indexes.nasdaqomx.com/Index/Overview/NDX"
+  - alias_id: index-RUSSELL2000
+    canonical_id: "INDEX:RUSSELL2000"
+    surface: "Russell 2000"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: ftse-russell-2000
+    source_url: "https://www.lseg.com/en/ftse-russell/indices/russell-2000-index"
+  - alias_id: index-RUSSELL2000-name
+    canonical_id: "INDEX:RUSSELL2000"
+    surface: "Russell 2000 Index"
+    match_mode: normalized_phrase
+    requires_context: false
+    source_id: ftse-russell-2000
+    source_url: "https://www.lseg.com/en/ftse-russell/indices/russell-2000-index"
+
+context_rules: {}
+
+relationships:
+  - relationship_id: SPY-tracks-SP500
+    relationship_type: tracks_benchmark
+    subject_id: SPY
+    object_id: "INDEX:SP500"
+    valid_from: "1993-01-22 00:00:00-05:00"
+    valid_to: null
+    source_id: ssga-spy
+    source_url: "https://www.ssga.com/us/en/intermediary/etfs/spdr-sp-500-etf-trust-spy"
+  - relationship_id: QQQ-tracks-NASDAQ100
+    relationship_type: tracks_benchmark
+    subject_id: QQQ
+    object_id: "INDEX:NASDAQ100"
+    valid_from: "1999-03-10 00:00:00-05:00"
+    valid_to: null
+    source_id: invesco-qqq
+    source_url: "https://www.invesco.com/qqq-etf/en/home.html"
+  - relationship_id: IWM-tracks-RUSSELL2000
+    relationship_type: tracks_benchmark
+    subject_id: IWM
+    object_id: "INDEX:RUSSELL2000"
+    valid_from: "2000-05-22 00:00:00-04:00"
+    valid_to: null
+    source_id: ishares-iwm
+    source_url: "https://www.ishares.com/us/products/239710/ishares-russell-2000-etf"

src/range_news/_core/catalogs/lexical.yml

@@ -0,0 +1,744 @@
+catalog_version: "relevance-general-economy-lexical-2026-09-01-v1"
+source_as_of: "2026-09-01"
+normalization_version: "financial-phrase-nfkc-v2"
+
+rules:
+  - rule_id: central-bank-federal-reserve
+    entity_concept: central_bank
+    tag_type: macroeconomic
+    target_id: "CENTRAL_BANK:FED"
+    market_wide_authorized: true
+    phrases:
+      - "Federal Reserve"
+      - "Federal Reserve Board"
+      - "Federal Open Market Committee"
+      - FOMC
+    source_id: federal-reserve
+    source_url: "https://www.federalreserve.gov/monetarypolicy.htm"
+  - rule_id: central-bank-global
+    entity_concept: central_bank
+    tag_type: macroeconomic
+    target_id: "CENTRAL_BANK:GLOBAL"
+    market_wide_authorized: true
+    phrases:
+      - "European Central Bank"
+      - "Bank of England"
+      - "Bank of Japan"
+      - "People's Bank of China"
+    source_id: central-banks
+    source_url: "https://www.bis.org/cbanks.htm"
+  - rule_id: monetary-policy-rates
+    entity_concept: monetary_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:POLICY_RATE"
+    market_wide_authorized: true
+    phrases:
+      - "federal funds rate"
+      - "policy rate decision"
+      - "interest rate decision"
+      - "rate hike"
+      - "rate cut"
+      - "interest-rate hike"
+      - "interest-rate cut"
+    source_id: federal-reserve
+    source_url: "https://www.federalreserve.gov/monetarypolicy.htm"
+  - rule_id: monetary-policy-balance-sheet
+    entity_concept: monetary_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:MONETARY_BALANCE_SHEET"
+    market_wide_authorized: true
+    phrases:
+      - "quantitative easing"
+      - "quantitative tightening"
+      - "balance sheet runoff"
+      - "central bank asset purchases"
+      - "bond purchase program"
+    source_id: federal-reserve
+    source_url: "https://www.federalreserve.gov/monetarypolicy.htm"
+  - rule_id: central-bank-fed-shorthand
+    entity_concept: central_bank
+    tag_type: macroeconomic
+    target_id: "CENTRAL_BANK:FED"
+    market_wide_authorized: true
+    phrases: [Fed]
+    case_sensitive: true
+    context_window_chars: 96
+    context_any: [rate, rates, policy, inflation, FOMC, official, chair]
+    source_id: federal-reserve
+    source_url: "https://www.federalreserve.gov/monetarypolicy.htm"
+
+  - rule_id: inflation-consumer-prices
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:CPI"
+    market_wide_authorized: true
+    phrases:
+      - "Consumer Price Index"
+      - "CPI inflation"
+      - "core CPI"
+      - "headline CPI"
+    source_id: bls-cpi
+    source_url: "https://www.bls.gov/cpi/"
+  - rule_id: inflation-pce-prices
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:PCE"
+    market_wide_authorized: true
+    phrases:
+      - "personal consumption expenditures price index"
+      - "PCE inflation"
+      - "core PCE"
+      - "PCE price index"
+    source_id: bea-pce
+    source_url: "https://www.bea.gov/data/personal-consumption-expenditures-price-index"
+  - rule_id: inflation-producer-prices
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:PPI"
+    market_wide_authorized: true
+    phrases:
+      - "Producer Price Index"
+      - "PPI inflation"
+      - "core PPI"
+    source_id: bls-ppi
+    source_url: "https://www.bls.gov/ppi/"
+  - rule_id: inflation-expectations
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:INFLATION_EXPECTATIONS"
+    market_wide_authorized: true
+    phrases:
+      - "inflation expectations"
+      - "breakeven inflation"
+      - "five-year inflation expectations"
+      - "long-term inflation expectations"
+    source_id: fred-inflation-expectations
+    source_url: "https://fred.stlouisfed.org/"
+  - rule_id: inflation-cpi-acronym
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:CPI"
+    market_wide_authorized: true
+    phrases: [CPI]
+    case_sensitive: true
+    context_window_chars: 64
+    context_any: [inflation, price, prices, index, consumer]
+    source_id: bls-cpi
+    source_url: "https://www.bls.gov/cpi/"
+  - rule_id: inflation-pce-acronym
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:PCE"
+    market_wide_authorized: true
+    phrases: [PCE]
+    case_sensitive: true
+    context_window_chars: 64
+    context_any: [inflation, price, prices, index, spending]
+    source_id: bea-pce
+    source_url: "https://www.bea.gov/data/personal-consumption-expenditures-price-index"
+  - rule_id: inflation-ppi-acronym
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:PPI"
+    market_wide_authorized: true
+    phrases: [PPI]
+    case_sensitive: true
+    context_window_chars: 64
+    context_any: [inflation, price, prices, index, producer]
+    source_id: bls-ppi
+    source_url: "https://www.bls.gov/ppi/"
+
+  - rule_id: employment-payrolls
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:PAYROLLS"
+    market_wide_authorized: true
+    phrases:
+      - "nonfarm payrolls"
+      - "nonfarm payroll employment"
+      - "payroll employment"
+      - "employment situation report"
+    source_id: bls-employment
+    source_url: "https://www.bls.gov/ces/"
+  - rule_id: employment-unemployment
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:UNEMPLOYMENT"
+    market_wide_authorized: true
+    phrases:
+      - "unemployment rate"
+      - "labor force participation rate"
+      - "underemployment rate"
+    source_id: bls-employment
+    source_url: "https://www.bls.gov/ces/"
+  - rule_id: employment-claims
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:JOBLESS_CLAIMS"
+    market_wide_authorized: true
+    phrases:
+      - "initial jobless claims"
+      - "continuing jobless claims"
+      - "unemployment insurance claims"
+    source_id: dol-unemployment-claims
+    source_url: "https://oui.doleta.gov/unemploy/claims.asp"
+  - rule_id: employment-job-openings
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:JOLTS"
+    market_wide_authorized: true
+    phrases:
+      - "Job Openings and Labor Turnover Survey"
+      - "JOLTS report"
+      - "job openings data"
+    source_id: bls-jolts
+    source_url: "https://www.bls.gov/jlt/"
+  - rule_id: employment-wages
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:WAGES"
+    market_wide_authorized: true
+    phrases:
+      - "average hourly earnings"
+      - "wage growth"
+      - "employment cost index"
+      - "unit labor costs"
+    source_id: bls-wages
+    source_url: "https://www.bls.gov/ces/"
+
+  - rule_id: growth-gdp
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:GDP"
+    market_wide_authorized: true
+    phrases:
+      - "gross domestic product"
+      - "real GDP"
+      - "GDP growth"
+      - "GDP contraction"
+    source_id: bea-gdp
+    source_url: "https://www.bea.gov/data/gdp/gross-domestic-product"
+  - rule_id: consumption-retail-sales
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:CONSUMPTION"
+    market_wide_authorized: true
+    phrases:
+      - "retail sales"
+      - "consumer spending"
+      - "personal consumption expenditures"
+    source_id: census-retail
+    source_url: "https://www.census.gov/retail/"
+  - rule_id: activity-industrial-production
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:INDUSTRIAL_PRODUCTION"
+    market_wide_authorized: true
+    phrases:
+      - "industrial production"
+      - "capacity utilization"
+      - "manufacturing output"
+    source_id: federal-reserve-industrial-production
+    source_url: "https://www.federalreserve.gov/releases/g17/current/"
+  - rule_id: activity-business-surveys
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:BUSINESS_SURVEYS"
+    market_wide_authorized: true
+    phrases:
+      - "Purchasing Managers' Index"
+      - "manufacturing PMI"
+      - "services PMI"
+      - "ISM manufacturing index"
+      - "ISM services index"
+    source_id: business-surveys
+    source_url: "https://fred.stlouisfed.org/"
+  - rule_id: activity-confidence
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:CONFIDENCE"
+    market_wide_authorized: true
+    phrases:
+      - "consumer confidence"
+      - "consumer sentiment"
+      - "business confidence"
+    source_id: confidence-surveys
+    source_url: "https://fred.stlouisfed.org/"
+  - rule_id: activity-housing
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:HOUSING"
+    market_wide_authorized: true
+    phrases:
+      - "housing starts"
+      - "building permits"
+      - "existing home sales"
+      - "new home sales"
+      - "pending home sales"
+    source_id: census-housing
+    source_url: "https://www.census.gov/construction/nrc/"
+  - rule_id: activity-durable-goods
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:DURABLE_GOODS"
+    market_wide_authorized: true
+    phrases:
+      - "durable goods orders"
+      - "factory orders"
+      - "core capital goods orders"
+    source_id: census-manufacturing
+    source_url: "https://www.census.gov/manufacturing/m3/"
+  - rule_id: growth-gdp-acronym
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:GDP"
+    market_wide_authorized: true
+    phrases: [GDP]
+    case_sensitive: true
+    context_window_chars: 64
+    context_any: [growth, economy, economic, output, contraction]
+    source_id: bea-gdp
+    source_url: "https://www.bea.gov/data/gdp/gross-domestic-product"
+  - rule_id: activity-pmi-acronym
+    entity_concept: macroeconomic_indicator
+    tag_type: macroeconomic
+    target_id: "MACRO:BUSINESS_SURVEYS"
+    market_wide_authorized: true
+    phrases: [PMI]
+    case_sensitive: true
+    context_window_chars: 64
+    context_any: [manufacturing, services, business, survey, index]
+    source_id: business-surveys
+    source_url: "https://fred.stlouisfed.org/"
+
+  - rule_id: rates-treasury-yields
+    entity_concept: market_rate
+    tag_type: macroeconomic
+    target_id: "MACRO:TREASURY_YIELDS"
+    market_wide_authorized: true
+    phrases:
+      - "Treasury yield"
+      - "Treasury yields"
+      - "10-year yield"
+      - "ten-year yield"
+      - "2-year yield"
+      - "two-year yield"
+    source_id: us-treasury-rates
+    source_url: "https://home.treasury.gov/resource-center/data-chart-center/interest-rates"
+  - rule_id: rates-yield-curve
+    entity_concept: market_rate
+    tag_type: macroeconomic
+    target_id: "MACRO:YIELD_CURVE"
+    market_wide_authorized: true
+    phrases:
+      - "yield curve"
+      - "yield curve inversion"
+      - "inverted yield curve"
+      - "term premium"
+    source_id: us-treasury-rates
+    source_url: "https://home.treasury.gov/resource-center/data-chart-center/interest-rates"
+  - rule_id: credit-conditions
+    entity_concept: financial_conditions
+    tag_type: macroeconomic
+    target_id: "MACRO:CREDIT_CONDITIONS"
+    market_wide_authorized: true
+    phrases:
+      - "credit spreads"
+      - "credit spread"
+      - "high-yield spread"
+      - "investment-grade spread"
+      - "credit conditions"
+      - "credit crunch"
+      - "lending standards"
+    source_id: financial-conditions
+    source_url: "https://fred.stlouisfed.org/"
+  - rule_id: currency-dollar
+    entity_concept: currency_market
+    tag_type: macroeconomic
+    target_id: "MACRO:US_DOLLAR"
+    market_wide_authorized: true
+    phrases:
+      - "U.S. dollar index"
+      - "US dollar index"
+      - "dollar index"
+      - "currency intervention"
+      - "foreign exchange intervention"
+    source_id: currency-markets
+    source_url: "https://home.treasury.gov/"
+  - rule_id: commodities-energy
+    entity_concept: commodity_market
+    tag_type: macroeconomic
+    target_id: "MACRO:ENERGY_PRICES"
+    market_wide_authorized: true
+    phrases:
+      - "crude oil prices"
+      - "oil prices"
+      - "natural gas prices"
+      - "OPEC production"
+      - "energy prices"
+    source_id: eia-energy
+    source_url: "https://www.eia.gov/petroleum/"
+  - rule_id: commodities-industrial-metals
+    entity_concept: commodity_market
+    tag_type: macroeconomic
+    target_id: "MACRO:COMMODITIES"
+    market_wide_authorized: true
+    phrases:
+      - "copper prices"
+      - "industrial metals prices"
+      - "commodity price shock"
+    source_id: commodity-markets
+    source_url: "https://fred.stlouisfed.org/"
+
+  - rule_id: fiscal-budget
+    entity_concept: fiscal_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:FISCAL_POLICY"
+    market_wide_authorized: true
+    phrases:
+      - "federal budget deficit"
+      - "fiscal stimulus"
+      - "fiscal tightening"
+      - "government spending package"
+      - "tax legislation"
+    source_id: cbo-budget
+    source_url: "https://www.cbo.gov/topics/budget"
+  - rule_id: fiscal-debt-limit
+    entity_concept: fiscal_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:DEBT_LIMIT"
+    market_wide_authorized: true
+    phrases:
+      - "debt ceiling"
+      - "debt limit"
+      - "Treasury cash balance"
+      - "extraordinary measures"
+    source_id: us-treasury
+    source_url: "https://home.treasury.gov/"
+  - rule_id: fiscal-government-shutdown
+    entity_concept: fiscal_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:GOVERNMENT_SHUTDOWN"
+    market_wide_authorized: true
+    phrases:
+      - "government shutdown"
+      - "federal government shutdown"
+      - "shutdown deadline"
+    source_id: us-budget
+    source_url: "https://www.cbo.gov/topics/budget"
+  - rule_id: trade-tariffs
+    entity_concept: trade_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:TARIFFS"
+    market_wide_authorized: true
+    phrases:
+      - "tariff increase"
+      - "tariff cuts"
+      - "new tariffs"
+      - "trade war"
+      - "import duties"
+    source_id: ustr-trade-enforcement
+    source_url: "https://ustr.gov/issue-areas/enforcement"
+  - rule_id: trade-controls
+    entity_concept: trade_policy
+    tag_type: macroeconomic
+    target_id: "MACRO:TRADE_CONTROLS"
+    market_wide_authorized: true
+    phrases:
+      - "export controls"
+      - "import restrictions"
+      - "trade restrictions"
+      - "trade embargo"
+    source_id: ustr-trade-enforcement
+    source_url: "https://ustr.gov/issue-areas/enforcement"
+  - rule_id: supply-chain
+    entity_concept: economic_disruption
+    tag_type: market_event
+    target_id: "MARKET:SUPPLY_CHAIN"
+    market_wide_authorized: true
+    detection_method: event_rule
+    event_family: supply_chain_disruption
+    phrases:
+      - "supply chain disruption"
+      - "shipping disruption"
+      - "port strike"
+      - "semiconductor shortage"
+      - "freight bottleneck"
+    source_id: general-economy-taxonomy
+    source_url: "https://www.nber.org/research/business-cycle-dating"
+  - rule_id: business-cycle
+    entity_concept: business_cycle
+    tag_type: macroeconomic
+    target_id: "MACRO:BUSINESS_CYCLE"
+    market_wide_authorized: true
+    phrases:
+      - recession
+      - "economic contraction"
+      - "soft landing"
+      - "hard landing"
+      - stagflation
+    source_id: nber-business-cycle
+    source_url: "https://www.nber.org/research/business-cycle-dating"
+
+  - rule_id: financial-stability
+    entity_concept: financial_stability
+    tag_type: market_event
+    target_id: "MARKET:FINANCIAL_STABILITY"
+    market_wide_authorized: true
+    detection_method: event_rule
+    event_family: financial_stability
+    phrases:
+      - "financial stability"
+      - "systemic risk"
+      - "liquidity facility"
+      - "emergency lending facility"
+      - "market functioning facility"
+    source_id: federal-reserve-financial-stability
+    source_url: "https://www.federalreserve.gov/publications/financial-stability-report.htm"
+  - rule_id: banking-stress
+    entity_concept: financial_stability
+    tag_type: market_event
+    target_id: "MARKET:BANKING_STRESS"
+    market_wide_authorized: true
+    detection_method: event_rule
+    event_family: banking_stress
+    phrases:
+      - "bank failure"
+      - "banking crisis"
+      - "bank run"
+      - "deposit flight"
+      - "emergency bank rescue"
+    source_id: fdic-bank-failures
+    source_url: "https://www.fdic.gov/resources/resolutions/bank-failures/failed-bank-list/"
+  - rule_id: market-volatility
+    entity_concept: market_condition
+    tag_type: market_event
+    target_id: "MARKET:VOLATILITY"
+    market_wide_authorized: true
+    detection_method: event_rule
+    event_family: market_volatility
+    phrases:
+      - "market volatility"
+      - "volatility spike"
+      - "stock market selloff"
+      - "equity market selloff"
+      - "broad market rally"
+    source_id: market-conditions
+    source_url: "https://fred.stlouisfed.org/"
+  - rule_id: sovereign-risk
+    entity_concept: sovereign_risk
+    tag_type: market_event
+    target_id: "MARKET:SOVEREIGN_RISK"
+    market_wide_authorized: true
+    detection_method: event_rule
+    event_family: sovereign_risk
+    phrases:
+      - "sovereign default"
+      - "sovereign debt crisis"
+      - "credit rating downgrade of the United States"
+    source_id: sovereign-risk
+    source_url: "https://home.treasury.gov/"
+  - rule_id: economic-sanctions
+    entity_concept: geopolitical_economy
+    tag_type: market_event
+    target_id: "MARKET:SANCTIONS"
+    market_wide_authorized: true
+    detection_method: event_rule
+    event_family: economic_sanctions
+    phrases:
+      - "economic sanctions"
+      - "financial sanctions"
+      - "asset freeze sanctions"
+    source_id: us-treasury-sanctions
+    source_url: "https://ofac.treasury.gov/"
+
+  - rule_id: regulator-sec-name
+    entity_concept: financial_regulator
+    tag_type: regulatory
+    target_id: "REGULATOR:SEC"
+    market_wide_authorized: false
+    phrases:
+      - "Securities and Exchange Commission"
+      - "U.S. Securities and Exchange Commission"
+    source_id: sec-rules
+    source_url: "https://www.sec.gov/rules-regulations"
+  - rule_id: regulator-sec-acronym
+    entity_concept: financial_regulator
+    tag_type: regulatory
+    target_id: "REGULATOR:SEC"
+    market_wide_authorized: false
+    phrases: [SEC]
+    case_sensitive: true
+    context_window_chars: 96
+    context_any: [commission, regulator, filing, disclosure, investigation, charges, securities, rule, "market structure"]
+    source_id: sec-rules
+    source_url: "https://www.sec.gov/rules-regulations"
+  - rule_id: regulation-bank-capital
+    entity_concept: financial_regulator
+    tag_type: regulatory
+    target_id: "REGULATION:BANKING"
+    market_wide_authorized: true
+    phrases:
+      - "bank capital requirements"
+      - "capital rule"
+      - "stress test results"
+      - "deposit insurance reform"
+      - "liquidity coverage ratio"
+    source_id: banking-regulation
+    source_url: "https://www.fdic.gov/"
+
+  - rule_id: sector-communication-services
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:COMMUNICATION_SERVICES"
+    market_wide_authorized: false
+    phrases: ["communication services sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-consumer-discretionary
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:CONSUMER_DISCRETIONARY"
+    market_wide_authorized: false
+    phrases: ["consumer discretionary sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-consumer-staples
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:CONSUMER_STAPLES"
+    market_wide_authorized: false
+    phrases: ["consumer staples sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-energy
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:ENERGY"
+    market_wide_authorized: false
+    phrases: ["energy sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-financials
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:FINANCIALS"
+    market_wide_authorized: false
+    phrases: ["financials sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-health-care
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:HEALTH_CARE"
+    market_wide_authorized: false
+    phrases: ["health care sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-industrials
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:INDUSTRIALS"
+    market_wide_authorized: false
+    phrases: ["industrials sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-information-technology
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:INFORMATION_TECHNOLOGY"
+    market_wide_authorized: false
+    phrases: ["information technology sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-materials
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:MATERIALS"
+    market_wide_authorized: false
+    phrases: ["materials sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-real-estate
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:REAL_ESTATE"
+    market_wide_authorized: false
+    phrases: ["real estate sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+  - rule_id: sector-utilities
+    entity_concept: industry_or_sector
+    tag_type: sector_or_industry
+    target_id: "SECTOR:UTILITIES"
+    market_wide_authorized: false
+    phrases: ["utilities sector"]
+    source_id: sp-global-gics
+    source_url: "https://www.spglobal.com/spdji/en/landing/topic/gics/"
+
+  - rule_id: company-event-earnings
+    entity_concept: financial_instrument
+    tag_type: company_event
+    target_id: null
+    market_wide_authorized: false
+    detection_method: event_rule
+    event_family: earnings_or_profit_loss
+    phrases:
+      - "quarterly earnings"
+      - "earnings per share"
+      - "profit warning"
+    source_id: maintained-company-events
+    source_url: "https://www.sec.gov/edgar/search-and-access"
+  - rule_id: company-event-merger
+    entity_concept: company
+    tag_type: company_event
+    target_id: null
+    market_wide_authorized: false
+    detection_method: event_rule
+    event_family: merger_or_acquisition
+    phrases:
+      - "merger agreement"
+      - "acquisition agreement"
+      - "takeover offer"
+    source_id: maintained-company-events
+    source_url: "https://www.sec.gov/edgar/search-and-access"
+  - rule_id: company-event-distress
+    entity_concept: company
+    tag_type: company_event
+    target_id: null
+    market_wide_authorized: false
+    detection_method: event_rule
+    event_family: bankruptcy_or_distress
+    phrases:
+      - "filed for bankruptcy"
+      - "files for bankruptcy"
+      - "bankruptcy protection"
+    source_id: maintained-company-events
+    source_url: "https://www.sec.gov/edgar/search-and-access"
+  - rule_id: company-event-capital-return
+    entity_concept: financial_instrument
+    tag_type: company_event
+    target_id: null
+    market_wide_authorized: false
+    detection_method: event_rule
+    event_family: dividend_or_capital_return
+    phrases:
+      - "share repurchase"
+      - "stock buyback"
+      - "special dividend"
+    source_id: maintained-company-events
+    source_url: "https://www.sec.gov/edgar/search-and-access"
+  - rule_id: company-event-rating
+    entity_concept: financial_instrument
+    tag_type: company_event
+    target_id: null
+    market_wide_authorized: false
+    detection_method: event_rule
+    event_family: analyst_rating
+    phrases:
+      - "analyst upgrade"
+      - "analyst downgrade"
+      - "price target raised"
+      - "price target cut"
+    source_id: maintained-company-events
+    source_url: "https://www.sec.gov/edgar/search-and-access"

src/range_news/_core/config.py

@@ -0,0 +1,293 @@
+"""Strict configuration loader for the public news-relevance API."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+import yaml
+
+from .models import ExposureFamily
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent
+DEFAULT_CONFIG_PATH = _PACKAGE_ROOT / "configs" / "default.yml"
+_TOP_LEVEL_KEYS = {
+    "version",
+    "mode",
+    "catalogs",
+    "normalization",
+    "alias_policy_overrides",
+    "context_rules",
+    "market_wide_conjunctions",
+    "exposure_families",
+    "relationship_paths",
+    "constituent_evidence_enabled",
+    "licensed_adapters",
+    "precedence",
+    "relevant_k",
+    "ranked_k",
+}
+_TIE_BREAKERS = (
+    "accepted_tag_details_desc",
+    "independent_detection_methods_desc",
+    "article_timestamp_desc",
+    "article_id_asc",
+)
+
+
+def _mapping(value: object, name: str) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise TypeError(f"{name} must be a mapping")
+    return value
+
+
+def _exact_keys(value: Mapping[str, Any], allowed: set[str], name: str) -> None:
+    unknown = set(value) - allowed
+    if unknown:
+        raise ValueError(f"unknown {name} keys: {sorted(unknown)}")
+
+
+def _catalog_path(value: object, name: str, *, base_dir: Path) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{name} must be a non-empty path")
+    resolved = (base_dir / value).resolve()
+    if not resolved.is_file():
+        raise ValueError(f"{name} does not exist: {resolved}")
+    return resolved
+
+
+@dataclass(frozen=True, slots=True)
+class ContextRule:
+    window_chars: int
+    accept_any_clauses: tuple[tuple[str, ...], ...]
+    reject_any_terms: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class MarketWideConjunctionRule:
+    actor_phrases: tuple[str, ...]
+    actor_identifiers: tuple[str, ...]
+    action_phrases: tuple[str, ...]
+    object_phrases: tuple[str, ...]
+    scope_phrases: tuple[str, ...]
+    entity_concept: str
+    tag_type: str
+    target_id: str
+    event_family: str
+
+
+@dataclass(frozen=True, slots=True)
+class NewsRelevanceConfig:
+    version: str
+    mode: str
+    entity_catalog_path: Path
+    lexical_catalog_path: Path
+    alias_policy_overrides: Mapping[str, Mapping[str, Any]]
+    context_rules: Mapping[str, ContextRule]
+    market_wide_conjunctions: Mapping[str, MarketWideConjunctionRule]
+    exposure_members: Mapping[ExposureFamily, frozenset[str]]
+    relationship_paths: Mapping[str, tuple[str, ...]]
+    precedence: tuple[str, ...]
+    accepted_link_statuses: frozenset[str]
+    ranking_tiers: Mapping[str, int]
+    ranking_budget: int
+    constituent_evidence_enabled: bool
+
+
+def load_config(path: str | Path | None = None) -> NewsRelevanceConfig:
+    """Load a fail-closed configuration; unknown fields are rejected."""
+
+    config_path = Path(path).resolve() if path is not None else DEFAULT_CONFIG_PATH
+    catalog_root = config_path.parent if path is not None else _PACKAGE_ROOT
+    with config_path.open(encoding="utf-8") as handle:
+        root = yaml.safe_load(handle)
+    root = _mapping(root, "config")
+    _exact_keys(root, _TOP_LEVEL_KEYS, "top-level")
+    if root.get("mode") != "catalog_lite":
+        raise ValueError("only mode=catalog_lite is currently implemented")
+    if root.get("constituent_evidence_enabled") is not False:
+        raise ValueError("catalog_lite must fail closed on constituent evidence")
+    adapters = _mapping(root.get("licensed_adapters"), "licensed_adapters")
+    _exact_keys(adapters, {"crsp", "compustat"}, "licensed_adapters")
+    if any(value is not False for value in adapters.values()):
+        raise ValueError("licensed adapters are unavailable in the public core")
+
+    catalogs = _mapping(root.get("catalogs"), "catalogs")
+    _exact_keys(catalogs, {"entities", "lexical"}, "catalogs")
+    normalization = _mapping(root.get("normalization"), "normalization")
+    _exact_keys(normalization, {"version", "fuzzy_edits"}, "normalization")
+    if normalization != {
+        "version": "financial-phrase-nfkc-v2",
+        "fuzzy_edits": False,
+    }:
+        raise ValueError("the conservative v2 normalization contract is required")
+
+    overrides = _mapping(root.get("alias_policy_overrides"), "alias_policy_overrides")
+    override_values: dict[str, Mapping[str, Any]] = {}
+    for alias_id, raw in overrides.items():
+        value = _mapping(raw, f"alias_policy_overrides.{alias_id}")
+        _exact_keys(
+            value, {"context_required", "context_rule_id"}, f"alias override {alias_id}"
+        )
+        if not isinstance(value.get("context_required"), bool):
+            raise TypeError(f"alias override {alias_id} needs boolean context_required")
+        override_values[str(alias_id)] = MappingProxyType(dict(value))
+
+    rules = _mapping(root.get("context_rules"), "context_rules")
+    context_rules: dict[str, ContextRule] = {}
+    for rule_id, raw in rules.items():
+        value = _mapping(raw, f"context_rules.{rule_id}")
+        _exact_keys(
+            value,
+            {"window_chars", "accept_any_clauses", "reject_any_terms"},
+            f"context rule {rule_id}",
+        )
+        width = value.get("window_chars")
+        if isinstance(width, bool) or not isinstance(width, int) or width <= 0:
+            raise ValueError(f"context rule {rule_id} needs positive window_chars")
+        context_rules[str(rule_id)] = ContextRule(
+            window_chars=width,
+            accept_any_clauses=tuple(
+                tuple(str(term) for term in clause)
+                for clause in value.get("accept_any_clauses", ())
+            ),
+            reject_any_terms=tuple(
+                str(term) for term in value.get("reject_any_terms", ())
+            ),
+        )
+
+    raw_conjunctions = _mapping(
+        root.get("market_wide_conjunctions"), "market_wide_conjunctions"
+    )
+    market_wide_conjunctions: dict[str, MarketWideConjunctionRule] = {}
+    conjunction_keys = {
+        "actor_phrases",
+        "actor_identifiers",
+        "action_phrases",
+        "object_phrases",
+        "scope_phrases",
+        "entity_concept",
+        "tag_type",
+        "target_id",
+        "event_family",
+    }
+    for rule_id, raw in raw_conjunctions.items():
+        value = _mapping(raw, f"market_wide_conjunctions.{rule_id}")
+        _exact_keys(value, conjunction_keys, f"market-wide conjunction {rule_id}")
+        sequence_fields = (
+            "actor_phrases",
+            "actor_identifiers",
+            "action_phrases",
+            "object_phrases",
+            "scope_phrases",
+        )
+        sequences: dict[str, tuple[str, ...]] = {}
+        for field in sequence_fields:
+            raw_values = value.get(field)
+            if not isinstance(raw_values, list) or not raw_values:
+                raise TypeError(
+                    f"market-wide conjunction {rule_id}.{field} must be a non-empty list"
+                )
+            sequences[field] = tuple(str(item) for item in raw_values)
+        scalar_values = {}
+        for field in ("entity_concept", "tag_type", "target_id", "event_family"):
+            raw_value = value.get(field)
+            if not isinstance(raw_value, str) or not raw_value.strip():
+                raise TypeError(
+                    f"market-wide conjunction {rule_id}.{field} must be non-empty"
+                )
+            scalar_values[field] = raw_value
+        if scalar_values["target_id"] != ExposureFamily.MARKET_WIDE.value:
+            raise ValueError("market-wide conjunction target must be MARKET_WIDE")
+        market_wide_conjunctions[str(rule_id)] = MarketWideConjunctionRule(
+            **sequences,
+            **scalar_values,
+        )
+
+    raw_families = _mapping(root.get("exposure_families"), "exposure_families")
+    exposure_members: dict[ExposureFamily, frozenset[str]] = {}
+    seen_members: set[str] = set()
+    for family_name, raw in raw_families.items():
+        family = ExposureFamily(str(family_name))
+        value = _mapping(raw, f"exposure_families.{family_name}")
+        _exact_keys(value, {"canonical_members"}, f"exposure family {family_name}")
+        members = frozenset(
+            str(member) for member in value.get("canonical_members", ())
+        )
+        if not members or seen_members & members:
+            raise ValueError("exposure family members must be non-empty and disjoint")
+        seen_members.update(members)
+        exposure_members[family] = members
+
+    raw_paths = _mapping(root.get("relationship_paths"), "relationship_paths")
+    relationship_paths = {
+        str(canonical_id): tuple(str(item) for item in path_value)
+        for canonical_id, path_value in raw_paths.items()
+    }
+    if any(not path_value for path_value in relationship_paths.values()):
+        raise ValueError("relationship paths cannot be empty")
+
+    precedence = _mapping(root.get("precedence"), "precedence")
+    _exact_keys(precedence, {"detection_methods"}, "precedence")
+    methods = tuple(str(item) for item in precedence.get("detection_methods", ()))
+    if not methods or len(methods) != len(set(methods)):
+        raise ValueError("precedence detection methods must be unique and non-empty")
+
+    relevant = _mapping(root.get("relevant_k"), "relevant_k")
+    _exact_keys(relevant, {"accepted_link_statuses"}, "relevant_k")
+    link_statuses = frozenset(
+        str(item) for item in relevant.get("accepted_link_statuses", ())
+    )
+    if not link_statuses:
+        raise ValueError("Relevant-K requires accepted link statuses")
+
+    ranked = _mapping(root.get("ranked_k"), "ranked_k")
+    _exact_keys(ranked, {"strategy", "budget", "tiers", "tie_breakers"}, "ranked_k")
+    if ranked.get("strategy") != "per_bucket_exposure_lexicographic_v2":
+        raise ValueError("unsupported Ranked-K strategy")
+    if tuple(ranked.get("tie_breakers", ())) != _TIE_BREAKERS:
+        raise ValueError("Ranked-K tie-breakers differ from the frozen contract")
+    budget = ranked.get("budget")
+    if isinstance(budget, bool) or not isinstance(budget, int) or budget <= 0:
+        raise ValueError("ranked_k.budget must be a positive integer")
+    tiers_raw = _mapping(ranked.get("tiers"), "ranked_k.tiers")
+    tiers = {str(name): int(value) for name, value in tiers_raw.items()}
+    if any(value < 0 for value in tiers.values()):
+        raise ValueError("ranking tiers must be non-negative")
+    missing_conjunction_tiers = {
+        rule.tag_type
+        for rule in market_wide_conjunctions.values()
+        if rule.tag_type not in tiers
+    }
+    if missing_conjunction_tiers:
+        raise ValueError(
+            "market-wide conjunction tag types need ranking tiers: "
+            f"{sorted(missing_conjunction_tiers)}"
+        )
+
+    version = root.get("version")
+    if not isinstance(version, str) or not version.strip():
+        raise ValueError("version must be non-empty")
+    return NewsRelevanceConfig(
+        version=version,
+        mode="catalog_lite",
+        entity_catalog_path=_catalog_path(
+            catalogs.get("entities"), "catalogs.entities", base_dir=catalog_root
+        ),
+        lexical_catalog_path=_catalog_path(
+            catalogs.get("lexical"), "catalogs.lexical", base_dir=catalog_root
+        ),
+        alias_policy_overrides=MappingProxyType(override_values),
+        context_rules=MappingProxyType(context_rules),
+        market_wide_conjunctions=MappingProxyType(market_wide_conjunctions),
+        exposure_members=MappingProxyType(exposure_members),
+        relationship_paths=MappingProxyType(relationship_paths),
+        precedence=methods,
+        accepted_link_statuses=link_statuses,
+        ranking_tiers=MappingProxyType(tiers),
+        ranking_budget=budget,
+        constituent_evidence_enabled=False,
+    )

src/range_news/_core/configs/default.yml

@@ -0,0 +1,126 @@
+version: "relevance-general-economy-v1"
+mode: "catalog_lite"
+
+catalogs:
+  entities: "catalogs/entities.yml"
+  lexical: "catalogs/lexical.yml"
+
+normalization:
+  version: "financial-phrase-nfkc-v2"
+  fuzzy_edits: false
+
+alias_policy_overrides:
+  ticker-SPY:
+    context_required: true
+    context_rule_id: "ticker-collision-SPY-v1"
+
+context_rules:
+  ticker-collision-SPY-v1:
+    window_chars: 128
+    accept_any_clauses:
+      - [SPDR]
+      - [ETF]
+      - [fund, "S&P 500"]
+      - [shares, "S&P 500"]
+      - [ticker, market]
+      - [NYSE, Arca]
+    reject_any_terms:
+      - espionage
+      - "spy agency"
+      - "spy plane"
+      - "spy novel"
+      - "spy satellite"
+      - "Russian spy"
+      - spies
+
+market_wide_conjunctions:
+  sec-broad-rulemaking:
+    actor_phrases:
+      - "Securities and Exchange Commission"
+      - "U.S. Securities and Exchange Commission"
+    actor_identifiers: [SEC]
+    action_phrases:
+      - adopts
+      - adopted
+      - approves
+      - approved
+      - proposes
+      - proposed
+      - finalizes
+      - finalized
+      - rescinds
+      - rescinded
+    object_phrases:
+      - rule
+      - regulation
+      - "disclosure requirement"
+      - "market structure"
+    scope_phrases:
+      - "securities market"
+      - "equity market"
+      - "public companies"
+      - "broker-dealers"
+      - "stock exchanges"
+      - "clearing agencies"
+      - "all exchanges"
+    entity_concept: financial_regulator
+    tag_type: regulatory
+    target_id: MARKET_WIDE
+    event_family: broad_rulemaking
+
+exposure_families:
+  "EXPOSURE:SP500":
+    canonical_members: [SPY, "INDEX:SP500"]
+  "EXPOSURE:NASDAQ100":
+    canonical_members: [QQQ, "INDEX:NASDAQ100"]
+  "EXPOSURE:RUSSELL2000":
+    canonical_members: [IWM, "INDEX:RUSSELL2000"]
+
+relationship_paths:
+  SPY: [SPY-tracks-SP500]
+  QQQ: [QQQ-tracks-NASDAQ100]
+  IWM: [IWM-tracks-RUSSELL2000]
+
+constituent_evidence_enabled: false
+licensed_adapters:
+  crsp: false
+  compustat: false
+
+precedence:
+  detection_methods:
+    - exact_identifier
+    - exact_catalog_alias
+    - normalized_catalog_alias
+    - lexical_phrase
+    - regex_pattern
+    - event_rule
+    - frozen_gliner
+    - semantic
+    - source_metadata
+
+relevant_k:
+  accepted_link_statuses:
+    - direct_asset
+    - direct_benchmark
+    - resolved_exposure
+    - market_wide
+
+ranked_k:
+  strategy: "per_bucket_exposure_lexicographic_v2"
+  budget: 16
+  tiers:
+    direct_security: 0
+    benchmark_or_index: 1
+    constituent_or_issuer: 2
+    company_event: 2
+    sector_or_industry: 3
+    macroeconomic: 4
+    regulatory: 4
+    market_event: 4
+    market_wide: 4
+    semantic_financial_other: 5
+  tie_breakers:
+    - accepted_tag_details_desc
+    - independent_detection_methods_desc
+    - article_timestamp_desc
+    - article_id_asc

src/range_news/_core/indicator.py

@@ -0,0 +1,1417 @@
+"""Deterministic, traceable article-evidence construction."""
+
+from __future__ import annotations
+
+import hashlib
+import html
+import re
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+from typing import Literal
+
+from .catalogs import (
+    CatalogAlias,
+    CatalogBundle,
+    active_during,
+    alias_spans,
+    context_result,
+    find_normalized_phrase_spans,
+    lexical_spans,
+    load_catalogs,
+    normalize_financial_phrase,
+)
+from .config import NewsRelevanceConfig, load_config
+from .models import (
+    Article,
+    ArticleAdmissibilityDecision,
+    ArticleAdmissibilityStatus,
+    EvidencePath,
+    EvidenceStatus,
+    ExposureFamily,
+    ExposureRelevanceDecision,
+    ExposureRelevanceStatus,
+    IdentityResolution,
+    IdentityStatus,
+    Observation,
+    ObservationBundle,
+    RelevanceDecision,
+    parse_article_time,
+)
+
+_DETERMINISTIC_METHODS = {
+    "exact_identifier",
+    "exact_catalog_alias",
+    "normalized_catalog_alias",
+    "lexical_phrase",
+    "regex_pattern",
+    "event_rule",
+    "source_metadata",
+}
+_COMPLETED_LINKS = {
+    "direct_asset",
+    "direct_benchmark",
+    "resolved_exposure",
+    "market_wide",
+}
+_UNRESOLVED_EXPOSURE_TAGS = {
+    "direct_security",
+    "constituent_or_issuer",
+    "sector_or_industry",
+    "company_event",
+    "semantic_financial_other",
+}
+_MERMAID_MAX_EVIDENCE_CARDS = 4
+_MERMAID_MAX_ARTICLE_PREVIEW_CHARS = 260
+_MERMAID_SNIPPET_CONTEXT_CHARS = 52
+
+
+class _MermaidExplanation(str):
+    """Mermaid source that renders when it is the final value in a notebook cell."""
+
+    def _repr_markdown_(self) -> str:
+        return f"```mermaid\n{self}\n```"
+
+
+def _stable_id(prefix: str, *values: object) -> str:
+    payload = "\0".join(str(value) for value in values).encode("utf-8")
+    return f"{prefix}-{hashlib.sha256(payload).hexdigest()[:24]}"
+
+
+def _method_for(alias: CatalogAlias) -> str:
+    return {
+        "exact_identifier": "exact_identifier",
+        "exact_case_sensitive": "exact_catalog_alias",
+        "exact_casefold": "exact_catalog_alias",
+        "normalized_phrase": "normalized_catalog_alias",
+    }[alias.match_mode]
+
+
+def _exact_identifier_spans(text: str, value: str) -> list[tuple[int, int]]:
+    pattern = re.compile(rf"(?<![A-Za-z0-9_]){re.escape(value)}(?![A-Za-z0-9_])")
+    return [(match.start(), match.end()) for match in pattern.finditer(text)]
+
+
+class RelevanceIndicator:
+    """Build catalog-lite decisions without loading a model or using the network."""
+
+    def __init__(
+        self,
+        config: NewsRelevanceConfig | None = None,
+        catalogs: CatalogBundle | None = None,
+    ) -> None:
+        self.config = config or load_config()
+        self.catalogs = catalogs or load_catalogs(self.config)
+
+    @classmethod
+    def from_yaml(cls, path: str) -> RelevanceIndicator:
+        return cls(config=load_config(path))
+
+    def observe(self, article: Article) -> ObservationBundle:
+        """Create deterministic catalog, lexical, and event observations."""
+
+        text = article.text
+        observations: list[Observation] = []
+        candidates: list[tuple[CatalogAlias, int, int]] = []
+        for alias in self.catalogs.aliases:
+            candidates.extend(
+                (alias, start, end) for start, end in alias_spans(text, alias)
+            )
+        longest: dict[tuple[str, int], int] = {}
+        for alias, start, end in candidates:
+            key = (alias.canonical_id, start)
+            longest[key] = max(longest.get(key, 0), end)
+        for alias, start, end in candidates:
+            if end < longest[(alias.canonical_id, start)]:
+                continue
+            entity = self.catalogs.entities[alias.canonical_id]
+            context_ok, context_reason = True, "context_not_required"
+            if alias.requires_context:
+                context_ok, context_reason = context_result(
+                    text,
+                    start=start,
+                    end=end,
+                    rule=self.config.context_rules.get(alias.context_rule_id or ""),
+                )
+            observations.append(
+                Observation(
+                    observation_id=_stable_id(
+                        "obs2",
+                        article.article_id,
+                        start,
+                        end,
+                        entity.entity_concept,
+                        _method_for(alias),
+                        alias.alias_id,
+                    ),
+                    article_id=article.article_id,
+                    matched_surface=text[start:end],
+                    span_start=start,
+                    span_end=end,
+                    entity_concept=entity.entity_concept,
+                    detection_method=_method_for(alias),
+                    confidence=1.0,
+                    candidate_canonical_id=alias.canonical_id,
+                    catalog_entry_id=alias.alias_id,
+                    catalog_version=self.catalogs.entity_catalog_version,
+                    tag_type=(
+                        "direct_security"
+                        if entity.entity_kind == "fund"
+                        else (
+                            "benchmark_or_index"
+                            if entity.entity_kind == "index"
+                            else "constituent_or_issuer"
+                        )
+                    ),
+                    context_status=context_reason,
+                    source_id=alias.source_id,
+                )
+            )
+
+        for rule in self.catalogs.lexical_rules:
+            for phrase in rule.phrases:
+                for start, end in lexical_spans(text, rule, phrase):
+                    context_ok = True
+                    if rule.context_any:
+                        context = text[
+                            max(0, start - rule.context_window_chars) : min(
+                                len(text), end + rule.context_window_chars
+                            )
+                        ]
+                        context_ok = any(
+                            bool(find_normalized_phrase_spans(context, term))
+                            for term in rule.context_any
+                        )
+                    method = rule.detection_method
+                    stable_values: tuple[object, ...]
+                    if method == "event_rule":
+                        stable_values = (article.article_id, start, end, rule.rule_id)
+                    else:
+                        stable_values = (
+                            article.article_id,
+                            start,
+                            end,
+                            rule.entity_concept,
+                            method,
+                            self.catalogs.lexical_catalog_version,
+                        )
+                    observations.append(
+                        Observation(
+                            observation_id=_stable_id(
+                                "signal2" if method == "event_rule" else "obs2",
+                                *stable_values,
+                            ),
+                            article_id=article.article_id,
+                            matched_surface=text[start:end],
+                            span_start=start,
+                            span_end=end,
+                            entity_concept=rule.entity_concept,
+                            detection_method=method,
+                            confidence=1.0,
+                            candidate_canonical_id=rule.target_id,
+                            catalog_version=self.catalogs.lexical_catalog_version,
+                            rule_id=rule.rule_id,
+                            tag_type=rule.tag_type,
+                            event_family=rule.event_family,
+                            market_wide_authorized=rule.market_wide_authorized,
+                            context_status=(
+                                "lexical_context_satisfied"
+                                if context_ok
+                                else "lexical_context_not_satisfied"
+                            ),
+                            source_id=rule.source_id,
+                        )
+                    )
+        for rule_id, rule in self.config.market_wide_conjunctions.items():
+            actor_spans = [
+                span
+                for phrase in rule.actor_phrases
+                for span in find_normalized_phrase_spans(text, phrase)
+            ]
+            actor_spans.extend(
+                span
+                for identifier in rule.actor_identifiers
+                for span in _exact_identifier_spans(text, identifier)
+            )
+            action_spans = [
+                span
+                for phrase in rule.action_phrases
+                for span in find_normalized_phrase_spans(text, phrase)
+            ]
+            object_spans = [
+                span
+                for phrase in rule.object_phrases
+                for span in find_normalized_phrase_spans(text, phrase)
+            ]
+            scope_spans = [
+                span
+                for phrase in rule.scope_phrases
+                for span in find_normalized_phrase_spans(text, phrase)
+            ]
+            if not all((actor_spans, action_spans, object_spans, scope_spans)):
+                continue
+            contributing = [
+                actor_spans[0],
+                action_spans[0],
+                object_spans[0],
+                scope_spans[0],
+            ]
+            start = min(span[0] for span in contributing)
+            end = max(span[1] for span in contributing)
+            observations.append(
+                Observation(
+                    observation_id=_stable_id(
+                        "signal2", article.article_id, start, end, rule_id
+                    ),
+                    article_id=article.article_id,
+                    matched_surface=text[start:end],
+                    span_start=start,
+                    span_end=end,
+                    entity_concept=rule.entity_concept,
+                    detection_method="event_rule",
+                    confidence=1.0,
+                    candidate_canonical_id=rule.target_id,
+                    catalog_version=self.config.version,
+                    rule_id=rule_id,
+                    tag_type=rule.tag_type,
+                    event_family=rule.event_family,
+                    market_wide_authorized=True,
+                    context_status="market_wide_conjunction_satisfied",
+                    source_id="sec_rules_regulations",
+                )
+            )
+        return ObservationBundle(
+            article=article,
+            observations=tuple(
+                sorted(set(observations), key=lambda row: row.observation_id)
+            ),
+        )
+
+    def resolve(
+        self,
+        observations: ObservationBundle | Sequence[Observation],
+        as_of: datetime | str,
+    ) -> tuple[IdentityResolution, ...]:
+        """Resolve identities at ``as_of`` using effective-dated catalog records."""
+
+        timestamp = parse_article_time(as_of)
+        rows = (
+            observations.observations
+            if isinstance(observations, ObservationBundle)
+            else observations
+        )
+        output: list[IdentityResolution] = []
+        for observation in rows:
+            status = IdentityStatus.UNRESOLVED
+            canonical_id: str | None = None
+            reason = "observation_requires_entity_linker"
+            if observation.detection_method in {"frozen_gliner", "semantic"}:
+                if observation.candidate_canonical_id is not None:
+                    raise ValueError(
+                        "model observations cannot assign canonical identities"
+                    )
+                reason = "semantic_observation_requires_entity_linker"
+            elif observation.detection_method == "event_rule":
+                reason = "event_signal_without_entity_or_asset_link"
+            elif observation.catalog_entry_id is not None:
+                alias = next(
+                    item
+                    for item in self.catalogs.aliases
+                    if item.alias_id == observation.catalog_entry_id
+                )
+                if not active_during(
+                    timestamp, valid_from=alias.valid_from, valid_to=alias.valid_to
+                ):
+                    status = IdentityStatus.REJECTED
+                    reason = "inactive_at_article_time"
+                elif observation.context_status in {
+                    "context_clause_not_satisfied",
+                    "missing_context_rule",
+                    "explicit_collision_exclusion",
+                }:
+                    status = IdentityStatus.AMBIGUOUS
+                    reason = observation.context_status
+                else:
+                    status = IdentityStatus.ACCEPTED
+                    canonical_id = observation.candidate_canonical_id
+                    reason = "active_catalog_identity"
+            elif observation.detection_method == "lexical_phrase":
+                if observation.context_status == "lexical_context_not_satisfied":
+                    status = IdentityStatus.AMBIGUOUS
+                    reason = "lexical_context_not_satisfied"
+                else:
+                    status = IdentityStatus.ACCEPTED
+                    canonical_id = observation.candidate_canonical_id
+                    reason = "accepted_lexical_identity"
+            output.append(
+                IdentityResolution(
+                    resolution_id=_stable_id(
+                        "id2", observation.observation_id, status.value, reason
+                    ),
+                    observation_id=observation.observation_id,
+                    article_id=observation.article_id,
+                    status=status,
+                    canonical_id=canonical_id,
+                    reason_code=reason,
+                    resolution_method=observation.detection_method,
+                    catalog_version=observation.catalog_version,
+                )
+            )
+        return tuple(sorted(output, key=lambda row: row.resolution_id))
+
+    def _primary_observations(
+        self,
+        observations: Sequence[Observation],
+        resolutions: Sequence[IdentityResolution],
+    ) -> tuple[Observation, ...]:
+        resolution_map = {row.observation_id: row for row in resolutions}
+        groups: dict[tuple[object, ...], list[Observation]] = {}
+        for observation in observations:
+            key = (
+                observation.article_id,
+                observation.span_start,
+                observation.span_end,
+                normalize_financial_phrase(observation.matched_surface),
+            )
+            groups.setdefault(key, []).append(observation)
+        priority = {
+            method: index for index, method in enumerate(self.config.precedence)
+        }
+        selected: list[Observation] = []
+        for rows in groups.values():
+            accepted = [
+                row
+                for row in rows
+                if row.detection_method in _DETERMINISTIC_METHODS
+                and resolution_map[row.observation_id].status is IdentityStatus.ACCEPTED
+            ]
+            deterministic = [
+                row for row in rows if row.detection_method in _DETERMINISTIC_METHODS
+            ]
+            semantic = [
+                row
+                for row in rows
+                if row.detection_method in {"frozen_gliner", "semantic"}
+            ]
+            selected.extend(deterministic)
+            if not accepted and semantic:
+                selected.append(
+                    min(
+                        semantic,
+                        key=lambda row: (
+                            priority.get(row.detection_method, len(priority)),
+                            -(row.confidence or 0.0),
+                            row.observation_id,
+                        ),
+                    )
+                )
+        return tuple(sorted(selected, key=lambda row: row.observation_id))
+
+    def _evidence_paths(
+        self,
+        article: Article,
+        observations: Sequence[Observation],
+        resolutions: Sequence[IdentityResolution],
+    ) -> tuple[EvidencePath, ...]:
+        resolution_map = {row.observation_id: row for row in resolutions}
+        evidence: list[EvidencePath] = []
+        for observation in self._primary_observations(observations, resolutions):
+            resolution = resolution_map[observation.observation_id]
+            tag_type = observation.tag_type or "semantic_financial_other"
+            identity_ids = (
+                ()
+                if observation.detection_method == "event_rule"
+                else (resolution.resolution_id,)
+            )
+
+            def add(
+                *,
+                status: EvidenceStatus,
+                link_status: str,
+                tag_detail: str,
+                target_id: str | None,
+                family: ExposureFamily | None,
+                reason: str,
+                relationship_ids: tuple[str, ...] = (),
+                market_wide: bool = False,
+                tag_type_override: str | None = None,
+                _observation: Observation = observation,
+                _identity_ids: tuple[str, ...] = identity_ids,
+                _tag_type: str = tag_type,
+            ) -> None:
+                output_tag_type = tag_type_override or (
+                    "market_wide" if market_wide else _tag_type
+                )
+                evidence.append(
+                    EvidencePath(
+                        evidence_id=_stable_id(
+                            "ev2", _observation.observation_id, link_status, reason
+                        ),
+                        article_id=article.article_id,
+                        tag_type=output_tag_type,
+                        tag_detail=tag_detail,
+                        matched_surface=_observation.matched_surface,
+                        detection_method=_observation.detection_method,
+                        status=status,
+                        link_status=link_status,
+                        target_id=target_id,
+                        exposure_family=family,
+                        reason_code=reason,
+                        tier=self.config.ranking_tiers[output_tag_type],
+                        observation_ids=(_observation.observation_id,),
+                        identity_resolution_ids=_identity_ids,
+                        relationship_ids=relationship_ids,
+                        catalog_version=_observation.catalog_version,
+                        event_family=_observation.event_family,
+                        explicit_market_wide_rule=market_wide,
+                    )
+                )
+
+            if resolution.status is IdentityStatus.REJECTED:
+                rejected_detail = (
+                    self.catalogs.entities[
+                        observation.candidate_canonical_id or ""
+                    ].canonical_name
+                    if observation.catalog_entry_id is not None
+                    else observation.candidate_canonical_id
+                    or observation.rule_id
+                    or tag_type
+                )
+                add(
+                    status=EvidenceStatus.REJECTED,
+                    link_status="rejected",
+                    tag_detail=rejected_detail,
+                    target_id=None,
+                    family=None,
+                    reason=resolution.reason_code,
+                )
+                continue
+            if (
+                resolution.status is IdentityStatus.AMBIGUOUS
+                and observation.catalog_entry_id is not None
+            ):
+                entity = self.catalogs.entities[
+                    observation.candidate_canonical_id or ""
+                ]
+                add(
+                    status=EvidenceStatus.UNRESOLVED,
+                    link_status="unresolved",
+                    tag_detail=entity.canonical_name,
+                    target_id=None,
+                    family=None,
+                    reason=resolution.reason_code,
+                )
+                continue
+            if observation.detection_method == "event_rule":
+                if observation.market_wide_authorized:
+                    add(
+                        status=EvidenceStatus.ACCEPTED,
+                        link_status="market_wide",
+                        tag_detail=observation.rule_id or tag_type,
+                        target_id=ExposureFamily.MARKET_WIDE.value,
+                        family=ExposureFamily.MARKET_WIDE,
+                        reason="explicit_market_wide_rule",
+                        market_wide=True,
+                    )
+                    continue
+                add(
+                    status=EvidenceStatus.UNRESOLVED,
+                    link_status="unresolved",
+                    tag_detail=observation.rule_id or tag_type,
+                    target_id=None,
+                    family=None,
+                    reason="event_signal_without_entity_or_asset_link",
+                )
+                continue
+            if observation.detection_method in {"frozen_gliner", "semantic"}:
+                add(
+                    status=EvidenceStatus.UNRESOLVED,
+                    link_status="unresolved",
+                    tag_detail=observation.entity_concept,
+                    target_id=None,
+                    family=None,
+                    reason="semantic_observation_requires_entity_linker",
+                )
+                continue
+            if observation.catalog_entry_id is not None:
+                canonical_id = resolution.canonical_id
+                if canonical_id is None:
+                    raise ValueError("accepted catalog identity lost its canonical ID")
+                entity = self.catalogs.entities[canonical_id]
+                family = self.catalogs.exposure_family_for(canonical_id, self.config)
+                if entity.entity_kind == "fund" and family is not None:
+                    add(
+                        status=EvidenceStatus.ACCEPTED,
+                        link_status="direct_asset",
+                        tag_detail=entity.canonical_name,
+                        target_id=canonical_id,
+                        family=family,
+                        reason="accepted_direct_asset_identity",
+                    )
+                    relationships = self.catalogs.active_relationship_path(
+                        canonical_id, article.timestamp, self.config
+                    )
+                    if relationships:
+                        add(
+                            status=EvidenceStatus.ACCEPTED,
+                            link_status="resolved_exposure",
+                            tag_detail=family.value,
+                            target_id=family.value,
+                            family=family,
+                            reason="active_complete_exposure_path",
+                            relationship_ids=relationships,
+                            tag_type_override="benchmark_or_index",
+                        )
+                elif entity.entity_kind == "index" and family is not None:
+                    add(
+                        status=EvidenceStatus.ACCEPTED,
+                        link_status="direct_benchmark",
+                        tag_detail=entity.canonical_name,
+                        target_id=canonical_id,
+                        family=family,
+                        reason="accepted_direct_benchmark_identity",
+                    )
+                else:
+                    add(
+                        status=EvidenceStatus.UNRESOLVED,
+                        link_status="unresolved",
+                        tag_detail=entity.canonical_name,
+                        target_id=canonical_id,
+                        family=None,
+                        reason="identity_resolved_without_relevance_path",
+                    )
+                continue
+            market_wide = (
+                resolution.status is IdentityStatus.ACCEPTED
+                and observation.market_wide_authorized
+            )
+            add(
+                status=(
+                    EvidenceStatus.ACCEPTED
+                    if market_wide
+                    else EvidenceStatus.UNRESOLVED
+                ),
+                link_status="market_wide" if market_wide else "unresolved",
+                tag_detail=observation.rule_id or observation.entity_concept,
+                target_id=(
+                    "MARKET_WIDE" if market_wide else observation.candidate_canonical_id
+                ),
+                family=ExposureFamily.MARKET_WIDE if market_wide else None,
+                reason=(
+                    "explicit_market_wide_rule"
+                    if market_wide
+                    else "identity_resolved_without_relevance_path"
+                ),
+                market_wide=market_wide,
+            )
+        return tuple(sorted(set(evidence), key=lambda row: row.evidence_id))
+
+    def assess_article(
+        self,
+        article: Article,
+        observations: Sequence[Observation],
+        resolutions: Sequence[IdentityResolution],
+    ) -> ArticleAdmissibilityDecision:
+        paths = self._evidence_paths(article, observations, resolutions)
+        accepted = tuple(
+            path for path in paths if path.status is EvidenceStatus.ACCEPTED
+        )
+        unresolved = tuple(
+            path for path in paths if path.status is EvidenceStatus.UNRESOLVED
+        )
+        rejected = tuple(
+            path for path in paths if path.status is EvidenceStatus.REJECTED
+        )
+        event_paths = tuple(
+            path for path in unresolved if path.event_family is not None
+        )
+        accepted_identities = {
+            row.observation_id
+            for row in resolutions
+            if row.status is IdentityStatus.ACCEPTED
+        }
+        accepted_nonsemantic = any(
+            row.observation_id in accepted_identities
+            and row.detection_method in _DETERMINISTIC_METHODS
+            for row in observations
+        )
+        semantic_unresolved = any(
+            path.detection_method in {"semantic", "frozen_gliner"}
+            for path in unresolved
+        )
+        if accepted or accepted_nonsemantic or event_paths:
+            status = ArticleAdmissibilityStatus.ACCEPTED
+            reason = "accepted_financial_evidence"
+        elif semantic_unresolved:
+            status = ArticleAdmissibilityStatus.PLAUSIBLE_UNRESOLVED
+            reason = "semantic_financial_evidence_requires_resolution"
+        else:
+            status = ArticleAdmissibilityStatus.REJECTED
+            reason = "no_accepted_financial_evidence"
+        return ArticleAdmissibilityDecision(
+            article_id=article.article_id,
+            status=status,
+            accepted_evidence=accepted,
+            unresolved_evidence=unresolved,
+            rejected_evidence=rejected,
+            reason_codes=(reason,),
+        )
+
+    def assess_exposure(
+        self,
+        article: Article,
+        exposure_family: ExposureFamily | str,
+        observations: Sequence[Observation],
+        resolutions: Sequence[IdentityResolution],
+    ) -> ExposureRelevanceDecision:
+        family = ExposureFamily(exposure_family)
+        paths = self._evidence_paths(article, observations, resolutions)
+        supported = tuple(
+            path
+            for path in paths
+            if path.status is EvidenceStatus.ACCEPTED
+            and path.link_status in _COMPLETED_LINKS
+            and path.exposure_family is family
+        )
+        if supported:
+            return ExposureRelevanceDecision(
+                article_id=article.article_id,
+                exposure_family=family,
+                status=ExposureRelevanceStatus.SUPPORTED,
+                evidence_paths=supported,
+                reason_codes=("completed_relevance_path",),
+            )
+        completed_elsewhere = any(
+            path.status is EvidenceStatus.ACCEPTED
+            and path.link_status in _COMPLETED_LINKS
+            for path in paths
+        )
+        unresolved = tuple(
+            path
+            for path in paths
+            if path.status is EvidenceStatus.UNRESOLVED
+            and path.tag_type in _UNRESOLVED_EXPOSURE_TAGS
+            and path.reason_code
+            not in {
+                "explicit_collision_exclusion",
+                "context_clause_not_satisfied",
+                "lexical_context_not_satisfied",
+            }
+        )
+        if (
+            family is not ExposureFamily.MARKET_WIDE
+            and not completed_elsewhere
+            and unresolved
+        ):
+            return ExposureRelevanceDecision(
+                article_id=article.article_id,
+                exposure_family=family,
+                status=ExposureRelevanceStatus.PLAUSIBLE_UNRESOLVED,
+                unresolved_paths=unresolved,
+                reason_codes=("missing_effective_dated_exposure_path",),
+            )
+        return ExposureRelevanceDecision(
+            article_id=article.article_id,
+            exposure_family=family,
+            status=ExposureRelevanceStatus.NOT_SUPPORTED,
+            reason_codes=("no_completed_relevance_path",),
+        )
+
+    def predict(
+        self,
+        article: Article,
+        exposure_families: Iterable[ExposureFamily | str] | None = None,
+        semantic_observations: Sequence[Observation] = (),
+    ) -> RelevanceDecision:
+        bundle = self.observe(article)
+        for observation in semantic_observations:
+            if observation.article_id != article.article_id:
+                raise ValueError("semantic observation article ID mismatch")
+            if observation.span_end > len(article.text):
+                raise ValueError("semantic observation span falls outside article text")
+            if (
+                article.text[observation.span_start : observation.span_end]
+                != observation.matched_surface
+            ):
+                raise ValueError(
+                    "semantic observation offsets do not match article text"
+                )
+            if observation.detection_method not in {"semantic", "frozen_gliner"}:
+                raise ValueError(
+                    "injected observations must use a semantic detection method"
+                )
+            if observation.candidate_canonical_id is not None:
+                raise ValueError("semantic observations cannot assign canonical IDs")
+        observations = tuple(
+            sorted(
+                {*bundle.observations, *semantic_observations},
+                key=lambda row: row.observation_id,
+            )
+        )
+        resolutions = self.resolve(observations, article.timestamp)
+        article_decision = self.assess_article(article, observations, resolutions)
+        requested = (
+            tuple(ExposureFamily(item) for item in exposure_families)
+            if exposure_families is not None
+            else tuple(ExposureFamily)
+        )
+        exposure_decisions = {
+            family: self.assess_exposure(article, family, observations, resolutions)
+            for family in requested
+        }
+        return RelevanceDecision(
+            article=article,
+            article_decision=article_decision,
+            exposure_decisions=exposure_decisions,
+            observations=observations,
+            resolutions=resolutions,
+        )
+
+    def explain(
+        self,
+        decision: RelevanceDecision,
+        *,
+        output_format: Literal["text", "mermaid"] = "text",
+        detail: Literal["summary", "details", "audit"] = "summary",
+    ) -> str:
+        """Explain a completed prediction without rerunning detection logic.
+
+        The default is a short explanation. ``detail="details"`` exposes the full
+        recorded evidence. ``detail="audit"`` remains as a backwards-compatible
+        alias. Mermaid results render natively in JupyterLab 4.1+ and Notebook 7.1+
+        while remaining string-compatible for logging or saving.
+        """
+
+        if detail not in {"summary", "details", "audit"}:
+            raise ValueError("detail must be 'summary' or 'details'")
+        show_details = detail in {"details", "audit"}
+        if output_format == "text":
+            return (
+                self._audit_text_explanation(decision)
+                if show_details
+                else self._text_explanation(decision)
+            )
+        if output_format == "mermaid":
+            source = (
+                self._audit_mermaid_explanation(decision)
+                if show_details
+                else self._mermaid_explanation(decision)
+            )
+            return _MermaidExplanation(source)
+        raise ValueError("output_format must be 'text' or 'mermaid'")
+
+    @staticmethod
+    def _group_paths(
+        paths: Sequence[EvidencePath],
+    ) -> tuple[tuple[EvidencePath, int], ...]:
+        """Collapse repeated occurrence-level evidence for readable explanations."""
+
+        groups: dict[tuple[object, ...], list[EvidencePath]] = {}
+        for path in paths:
+            key = (
+                path.tag_type,
+                path.tag_detail,
+                path.matched_surface,
+                path.detection_method,
+                path.status,
+                path.link_status,
+                path.target_id,
+                path.exposure_family,
+                path.reason_code,
+                path.relationship_ids,
+                path.catalog_version,
+                path.event_family,
+                path.explicit_market_wide_rule,
+            )
+            groups.setdefault(key, []).append(path)
+        return tuple(
+            (min(rows, key=lambda item: item.evidence_id), len(rows))
+            for _, rows in sorted(
+                groups.items(),
+                key=lambda item: min(row.evidence_id for row in item[1]),
+            )
+        )
+
+    @staticmethod
+    def _path_label(path: EvidencePath, occurrence_count: int = 1) -> str:
+        lineage = ", ".join(path.relationship_ids) or "no relationship lineage"
+        surface = path.matched_surface.replace("\r", " ").replace("\n", " ")
+        if len(surface) > 120:
+            surface = surface[:117].rstrip() + "..."
+        occurrences = (
+            f"; occurrences={occurrence_count}" if occurrence_count > 1 else ""
+        )
+        return (
+            f"{surface!r}: {path.tag_type}/{path.tag_detail}; "
+            f"status={path.status.value}; method={path.detection_method}; "
+            f"link={path.link_status}; reason={path.reason_code}; "
+            f"relationships={lineage}{occurrences}"
+        )
+
+    @staticmethod
+    def _status_heading(decision: RelevanceDecision) -> str:
+        return {
+            "relevant": "KEEP",
+            "needs_review": "CHECK",
+            "not_relevant": "IGNORE",
+        }[decision.status]
+
+    def _text_explanation(self, decision: RelevanceDecision) -> str:
+        lines = [
+            self._status_heading(decision),
+            f"Why: {decision.why}",
+        ]
+        if decision.relevant_to:
+            lines.append(f"Markets: {', '.join(decision.relevant_to)}")
+        lines.append(f"Article: {decision.article.article_id}")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _mermaid_text(value: object) -> str:
+        """Escape user text for a quoted Mermaid Markdown string."""
+
+        text = " ".join(str(value).replace("\r", " ").replace("\n", " ").split())
+        text = text.replace("\\", "/").replace('"', "'").replace("`", "'")
+        for character in ("*", "_", "[", "]"):
+            text = text.replace(character, f"\\{character}")
+        return html.escape(text, quote=False)
+
+    @classmethod
+    def _highlighted_span(
+        cls,
+        text: str,
+        *,
+        window_start: int,
+        match_start: int,
+        match_end: int,
+        window_end: int,
+    ) -> str:
+        open_marker = "\ue000"
+        close_marker = "\ue001"
+        value = (
+            text[window_start:match_start]
+            + open_marker
+            + text[match_start:match_end]
+            + close_marker
+            + text[match_end:window_end]
+        )
+        rendered = cls._mermaid_text(value)
+        return rendered.replace(open_marker, "**").replace(close_marker, "**")
+
+    @staticmethod
+    def _visual_observation_groups(
+        decision: RelevanceDecision,
+    ) -> tuple[tuple[Observation, int], ...]:
+        groups: dict[tuple[object, ...], list[Observation]] = {}
+        for observation in decision.observations:
+            key = (
+                observation.matched_surface.casefold(),
+                observation.entity_concept,
+                observation.detection_method,
+                observation.tag_type,
+                observation.context_status,
+            )
+            groups.setdefault(key, []).append(observation)
+        return tuple(
+            (min(rows, key=lambda row: (row.span_start, row.observation_id)), len(rows))
+            for _, rows in sorted(
+                groups.items(),
+                key=lambda item: min(
+                    (row.span_start, row.observation_id) for row in item[1]
+                ),
+            )
+        )
+
+    @classmethod
+    def _article_preview_lines(
+        cls,
+        decision: RelevanceDecision,
+        visible_groups: Sequence[tuple[Observation, int]],
+    ) -> list[str]:
+        article = decision.article
+        lines = [
+            f"**ARTICLE TEXT** · {cls._mermaid_text(article.article_id)}",
+            (
+                f"{cls._mermaid_text(article.source)} · "
+                f"{cls._mermaid_text(article.timestamp.isoformat())}"
+            ),
+        ]
+        text = article.text
+        observations = sorted(
+            decision.observations,
+            key=lambda row: (row.span_start, -(row.span_end - row.span_start)),
+        )
+        non_overlapping: list[Observation] = []
+        covered_until = -1
+        for observation in observations:
+            if observation.span_start < covered_until:
+                continue
+            non_overlapping.append(observation)
+            covered_until = observation.span_end
+
+        if len(text) <= _MERMAID_MAX_ARTICLE_PREVIEW_CHARS:
+            cursor = 0
+            pieces: list[str] = []
+            for observation in non_overlapping:
+                pieces.append(text[cursor : observation.span_start])
+                pieces.append("\ue000" + observation.matched_surface + "\ue001")
+                cursor = observation.span_end
+            pieces.append(text[cursor:])
+            preview = (
+                cls._mermaid_text("".join(pieces))
+                .replace("\ue000", "**")
+                .replace("\ue001", "**")
+            )
+            lines.append(preview or cls._mermaid_text(text))
+            return lines
+
+        if not visible_groups:
+            prefix = cls._mermaid_text(
+                text[:_MERMAID_MAX_ARTICLE_PREVIEW_CHARS].rstrip()
+            )
+            lines.append(f"{prefix} …")
+            return lines
+
+        lines.append(
+            f"{len(text):,} characters · relevant snippets shown below"
+        )
+        for observation, _ in visible_groups[:3]:
+            start = max(0, observation.span_start - _MERMAID_SNIPPET_CONTEXT_CHARS)
+            end = min(len(text), observation.span_end + _MERMAID_SNIPPET_CONTEXT_CHARS)
+            snippet = cls._highlighted_span(
+                text,
+                window_start=start,
+                match_start=observation.span_start,
+                match_end=observation.span_end,
+                window_end=end,
+            )
+            lines.append(
+                f"{'…' if start else ''}{snippet}{'…' if end < len(text) else ''}"
+            )
+        return lines
+
+    def _evidence_card(
+        self,
+        observation: Observation,
+        occurrence_count: int,
+        resolution_by_observation: dict[str, IdentityResolution],
+    ) -> tuple[list[str], str]:
+        tag_label = {
+            "direct_security": "Fund or ticker",
+            "benchmark_or_index": "Index or benchmark",
+            "constituent_or_issuer": "Company or issuer",
+            "macroeconomic": "Macroeconomic signal",
+            "macroeconomic_indicator": "Economic indicator",
+            "financial_regulator": "Financial regulator",
+            "sector_or_industry": "Sector or industry",
+            "company_event": "Company event",
+            "market_wide": "Broad-market signal",
+        }.get(
+            observation.tag_type or "",
+            (observation.tag_type or observation.entity_concept)
+            .replace("_", " ")
+            .title(),
+        )
+        method_label = {
+            "exact_identifier": "exact symbol",
+            "exact_catalog_alias": "exact catalog name",
+            "normalized_catalog_alias": "normalized catalog name",
+            "lexical_phrase": "saved financial phrase",
+            "regex_pattern": "financial pattern",
+            "event_rule": "event rule",
+            "source_metadata": "source metadata",
+            "semantic": "semantic candidate",
+            "frozen_gliner": "semantic entity candidate",
+        }.get(
+            observation.detection_method,
+            observation.detection_method.replace("_", " "),
+        )
+        count = f" × {occurrence_count}" if occurrence_count > 1 else ""
+        lines = [
+            f"**{self._mermaid_text(observation.matched_surface)}**{count}",
+            f"{self._mermaid_text(tag_label)} · {self._mermaid_text(method_label)}",
+        ]
+
+        resolution = resolution_by_observation.get(observation.observation_id)
+        if resolution is None:
+            lines.append("△ Identity was not resolved")
+            style = "review"
+        elif resolution.status is IdentityStatus.ACCEPTED:
+            canonical = resolution.canonical_id or observation.entity_concept
+            entity = self.catalogs.entities.get(canonical)
+            canonical_label = entity.canonical_name if entity is not None else canonical
+            lines.append(f"✓ Identity: {self._mermaid_text(canonical_label)}")
+            style = "verified"
+        elif resolution.status is IdentityStatus.AMBIGUOUS:
+            lines.append("✕ Identity is ambiguous")
+            style = "blocked"
+        elif resolution.status is IdentityStatus.REJECTED:
+            lines.append("✕ Identity was rejected")
+            style = "blocked"
+        else:
+            lines.append("△ Identity still needs resolution")
+            style = "review"
+
+        context_line = {
+            "context_clause_satisfied": "✓ Financial context confirmed",
+            "lexical_context_satisfied": "✓ Financial context confirmed",
+            "context_not_required": "• Context check not required",
+            "not_required": "• Context check not required",
+            "explicit_collision_exclusion": "✕ Blocked by non-financial context",
+            "context_clause_not_satisfied": "✕ Required financial context missing",
+            "lexical_context_not_satisfied": "✕ Required financial context missing",
+        }.get(observation.context_status)
+        if context_line:
+            lines.append(context_line)
+        if observation.context_status in {
+            "explicit_collision_exclusion",
+            "context_clause_not_satisfied",
+            "lexical_context_not_satisfied",
+        }:
+            style = "blocked"
+        return lines, style
+
+    @classmethod
+    def _market_card_lines(
+        cls,
+        family: ExposureFamily,
+        paths: Sequence[EvidencePath],
+    ) -> list[str]:
+        grouped: dict[tuple[str, str, str | None], list[EvidencePath]] = {}
+        for path in paths:
+            key = (path.link_status, path.matched_surface.casefold(), path.target_id)
+            grouped.setdefault(key, []).append(path)
+        resolved_surfaces = {
+            path.matched_surface.casefold()
+            for path in paths
+            if path.link_status == "resolved_exposure"
+        }
+        ordered = sorted(
+            grouped.values(),
+            key=lambda rows: (
+                {
+                    "resolved_exposure": 0,
+                    "direct_benchmark": 1,
+                    "market_wide": 2,
+                    "direct_asset": 3,
+                }.get(rows[0].link_status, 4),
+                rows[0].matched_surface.casefold(),
+            ),
+        )
+        lines = [f"**{cls._mermaid_text(family.label)}**"]
+        for rows in ordered:
+            path = rows[0]
+            if (
+                path.link_status == "direct_asset"
+                and path.matched_surface.casefold() in resolved_surfaces
+            ):
+                continue
+            count = f" × {len(rows)}" if len(rows) > 1 else ""
+            surface = cls._mermaid_text(path.matched_surface)
+            if path.link_status == "resolved_exposure":
+                value = f"{surface}{count} → {cls._mermaid_text(family.label)}"
+            elif path.link_status == "direct_benchmark":
+                value = f"{surface}{count} is the benchmark"
+            elif path.link_status == "direct_asset":
+                value = f"{surface}{count} is a tracked fund"
+            elif path.link_status == "market_wide":
+                value = f"{surface}{count} activates an approved broad-market rule"
+            else:
+                continue
+            lines.append(value)
+            if len(lines) == 4:
+                break
+        return lines
+
+    @staticmethod
+    def _mermaid_node(node_id: str, lines: Sequence[str], style: str) -> str:
+        return f'  {node_id}["`' + "\n".join(lines) + f'`"]:::{style}'
+
+    def _mermaid_explanation(self, decision: RelevanceDecision) -> str:
+        groups = self._visual_observation_groups(decision)
+        visible_groups = groups[:_MERMAID_MAX_EVIDENCE_CARDS]
+        resolution_by_observation = {
+            row.observation_id: row for row in decision.resolutions
+        }
+        lines = [
+            "flowchart TD",
+            "  accTitle: News relevance evidence path",
+            (
+                "  accDescr: Highlighted article evidence, verification gates, "
+                "market links, and the final relevance decision"
+            ),
+            self._mermaid_node(
+                "A",
+                self._article_preview_lines(decision, visible_groups),
+                "article",
+            ),
+            '  subgraph FOUND["1 · Evidence found in the article"]',
+            "    direction LR",
+        ]
+
+        evidence_nodes: list[str] = []
+        if visible_groups:
+            for index, (observation, count) in enumerate(visible_groups, start=1):
+                node = f"E{index}"
+                card_lines, style = self._evidence_card(
+                    observation, count, resolution_by_observation
+                )
+                lines.append(
+                    "  " + self._mermaid_node(node, card_lines, style).lstrip()
+                )
+                evidence_nodes.append(node)
+            hidden_count = len(groups) - len(visible_groups)
+            if hidden_count:
+                node = "EMORE"
+                lines.append(
+                    "  "
+                    + self._mermaid_node(
+                        node,
+                        (
+                            f"**+{hidden_count} more distinct match(es)**",
+                            "Use detail='details' for the full evidence trail",
+                        ),
+                        "muted",
+                    ).lstrip()
+                )
+                evidence_nodes.append(node)
+        else:
+            node = "E0"
+            lines.append(
+                "  "
+                + self._mermaid_node(
+                    node,
+                    (
+                        "**No financial evidence found**",
+                        "No saved alias, phrase, event, or semantic candidate matched",
+                    ),
+                    "muted",
+                ).lstrip()
+            )
+            evidence_nodes.append(node)
+        lines.append("  end")
+        for node in evidence_nodes:
+            lines.append(f'  A -->|"scan text"| {node}')
+
+        lines.append('  G1{"2 · Article evidence admissible?"}:::gate')
+        for node in evidence_nodes:
+            lines.append(f"  {node} --> G1")
+
+        result_style = {
+            "relevant": "accepted",
+            "needs_review": "review",
+            "not_relevant": "rejected",
+        }[decision.status]
+        result_lines = {
+            "relevant": [
+                "**KEEP**",
+                "Financial context accepted",
+                (
+                    "Markets: " + ", ".join(decision.relevant_to)
+                    if decision.relevant_to
+                    else "No verified configured market"
+                ),
+            ],
+            "needs_review": [
+                "**CHECK**",
+                "Potential financial evidence needs review",
+                "No verified configured market",
+            ],
+            "not_relevant": [
+                "**IGNORE**",
+                "No accepted financial evidence",
+            ],
+        }[decision.status]
+        result_lines = [
+            self._mermaid_text(value) if "**" not in value else value
+            for value in result_lines
+        ]
+        lines.append(self._mermaid_node("R", result_lines, result_style))
+
+        if decision.status == "not_relevant":
+            lines.append('  G1 -->|"No · filter stops here"| R')
+        else:
+            admissibility_label = (
+                "Yes · deterministic financial evidence"
+                if decision.status == "relevant"
+                else "Not yet · unresolved semantic evidence"
+            )
+            lines.append(
+                f'  G1 -->|"{admissibility_label}"| '
+                'G2{"3 · Configured market path complete?"}:::gate'
+            )
+            supported = [
+                (family, family_decision)
+                for family in ExposureFamily
+                if (
+                    (family_decision := decision.exposure_decisions.get(family))
+                    is not None
+                    and family_decision.status is ExposureRelevanceStatus.SUPPORTED
+                )
+            ]
+            if supported:
+                lines.extend(
+                    (
+                        '  subgraph PATHS["Verified market relationships"]',
+                        "    direction LR",
+                    )
+                )
+                market_nodes: list[str] = []
+                for index, (family, family_decision) in enumerate(supported, start=1):
+                    node = f"M{index}"
+                    lines.append(
+                        "  "
+                        + self._mermaid_node(
+                            node,
+                            self._market_card_lines(
+                                family, family_decision.evidence_paths
+                            ),
+                            "market",
+                        ).lstrip()
+                    )
+                    market_nodes.append(node)
+                lines.append("  end")
+                for node in market_nodes:
+                    lines.append(f'  G2 -->|"Yes"| {node}')
+                    lines.append(f"  {node} --> R")
+            else:
+                unresolved = any(
+                    family_decision.status
+                    is ExposureRelevanceStatus.PLAUSIBLE_UNRESOLVED
+                    for family_decision in decision.exposure_decisions.values()
+                )
+                market_lines = (
+                    (
+                        "**No completed market relationship**",
+                        "Potential links still need entity resolution",
+                    )
+                    if unresolved
+                    else (
+                        "**No completed market relationship**",
+                        "The article can still be kept as financial context",
+                    )
+                )
+                market_style = "review" if unresolved else "muted"
+                lines.append(self._mermaid_node("M0", market_lines, market_style))
+                lines.append('  G2 -->|"No"| M0')
+                lines.append("  M0 --> R")
+
+        lines.extend(
+            (
+                "  classDef article fill:#f8fafc,stroke:#475467,color:#101828,stroke-width:2px",
+                "  classDef verified fill:#ecfdf3,stroke:#079455,color:#074d31,stroke-width:1.5px",
+                "  classDef review fill:#fffaeb,stroke:#dc6803,color:#713b12,stroke-width:1.5px",
+                "  classDef blocked fill:#fef3f2,stroke:#d92d20,color:#7a271a,stroke-width:1.5px",
+                "  classDef gate fill:#eff8ff,stroke:#1570ef,color:#1849a9,stroke-width:2px",
+                "  classDef market fill:#f4f3ff,stroke:#6938ef,color:#42307d,stroke-width:1.5px",
+                "  classDef accepted fill:#dcfae6,stroke:#079455,color:#05603a,stroke-width:3px",
+                "  classDef rejected fill:#fee4e2,stroke:#d92d20,color:#7a271a,stroke-width:3px",
+                "  classDef muted fill:#f2f4f7,stroke:#98a2b3,color:#475467,stroke-dasharray:4 3",
+                "  style FOUND fill:#fcfcfd,stroke:#d0d5dd,stroke-dasharray:3 3",
+                "  style PATHS fill:#fcfcfd,stroke:#d0d5dd,stroke-dasharray:3 3",
+                "  linkStyle default stroke:#98a2b3,stroke-width:1.5px",
+            )
+        )
+        if not any(line.startswith('  subgraph PATHS') for line in lines):
+            lines.remove(
+                "  style PATHS fill:#fcfcfd,stroke:#d0d5dd,stroke-dasharray:3 3"
+            )
+        return "\n".join(lines)
+
+    def _audit_text_explanation(self, decision: RelevanceDecision) -> str:
+        lines = [
+            f"Article {decision.article.article_id}",
+            f"Article admissibility: {decision.article_decision.status.value}",
+        ]
+        article_paths = self._group_paths(
+            (
+                *decision.article_decision.accepted_evidence,
+                *decision.article_decision.unresolved_evidence,
+                *decision.article_decision.rejected_evidence,
+            )
+        )
+        if article_paths:
+            lines.append("Article evidence:")
+            lines.extend(
+                f"- {self._path_label(path, count)}" for path, count in article_paths
+            )
+        else:
+            reasons = ", ".join(decision.article_decision.reason_codes) or "none"
+            lines.append(f"Article evidence: none ({reasons})")
+
+        for family in ExposureFamily:
+            family_decision = decision.exposure_decisions.get(family)
+            if family_decision is None:
+                continue
+            lines.append(f"{family.value}: {family_decision.status.value}")
+            paths = self._group_paths(
+                (*family_decision.evidence_paths, *family_decision.unresolved_paths)
+            )
+            if paths:
+                lines.extend(
+                    f"- {self._path_label(path, count)}" for path, count in paths
+                )
+            else:
+                reasons = ", ".join(family_decision.reason_codes) or "none"
+                lines.append(f"- no supporting path ({reasons})")
+        return "\n".join(lines)
+
+    def _audit_mermaid_explanation(self, decision: RelevanceDecision) -> str:
+        def label(value: object) -> str:
+            return (
+                str(value)
+                .replace("\\", "\\\\")
+                .replace('"', "'")
+                .replace("\r", " ")
+                .replace("\n", " ")
+            )
+
+        article_id = label(decision.article.article_id)
+        article_status = decision.article_decision.status.value
+        lines = [
+            "flowchart TD",
+            f'  A["Article: {article_id}"] --> AD["Article admissibility: {article_status}"]',
+        ]
+        article_paths = self._group_paths(
+            (
+                *decision.article_decision.accepted_evidence,
+                *decision.article_decision.unresolved_evidence,
+                *decision.article_decision.rejected_evidence,
+            )
+        )
+        if article_paths:
+            for index, (path, count) in enumerate(article_paths, start=1):
+                lines.append(
+                    f'  A --> AE{index}["{label(self._path_label(path, count))}"]'
+                )
+                lines.append(f"  AE{index} --> AD")
+        else:
+            reasons = ", ".join(decision.article_decision.reason_codes) or "none"
+            lines.append(f'  A --> AN["No article evidence: {label(reasons)}"]')
+            lines.append("  AN --> AD")
+
+        for family_index, family in enumerate(ExposureFamily, start=1):
+            family_decision = decision.exposure_decisions.get(family)
+            if family_decision is None:
+                continue
+            family_node = f"F{family_index}"
+            lines.append(
+                f'  A --> {family_node}["{family.value}: '
+                f'{family_decision.status.value}"]'
+            )
+            paths = self._group_paths(
+                (*family_decision.evidence_paths, *family_decision.unresolved_paths)
+            )
+            if paths:
+                for path_index, (path, count) in enumerate(paths, start=1):
+                    path_node = f"{family_node}P{path_index}"
+                    lines.append(
+                        f'  {path_node}["{label(self._path_label(path, count))}"] '
+                        f"--> {family_node}"
+                    )
+            else:
+                reasons = ", ".join(family_decision.reason_codes) or "none"
+                lines.append(
+                    f'  {family_node}N["No supporting path: {label(reasons)}"] '
+                    f"--> {family_node}"
+                )
+        return "\n".join(lines)

src/range_news/_core/models.py

@@ -0,0 +1,418 @@
+"""Immutable public data contracts for news relevance decisions."""
+
+from __future__ import annotations
+
+import html
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from types import MappingProxyType
+from zoneinfo import ZoneInfo
+
+_ARTICLE_TIMEZONE = ZoneInfo("America/New_York")
+
+
+def parse_article_time(value: datetime | str) -> datetime:
+    """Parse an article time, interpreting naive values as America/New_York."""
+
+    if isinstance(value, datetime):
+        timestamp = value
+    elif isinstance(value, str) and value.strip():
+        timestamp = datetime.fromisoformat(value.strip())
+    else:
+        raise TypeError("timestamp must be a datetime or non-empty ISO-8601 string")
+    if timestamp.tzinfo is None:
+        timestamp = timestamp.replace(tzinfo=_ARTICLE_TIMEZONE)
+    return timestamp
+
+
+class ArticleAdmissibilityStatus(str, Enum):
+    ACCEPTED = "accepted"
+    PLAUSIBLE_UNRESOLVED = "plausible_unresolved"
+    REJECTED = "rejected"
+
+
+class ExposureRelevanceStatus(str, Enum):
+    SUPPORTED = "supported"
+    PLAUSIBLE_UNRESOLVED = "plausible_unresolved"
+    NOT_SUPPORTED = "not_supported"
+
+
+class ExposureFamily(str, Enum):
+    SP500 = "EXPOSURE:SP500"
+    NASDAQ100 = "EXPOSURE:NASDAQ100"
+    RUSSELL2000 = "EXPOSURE:RUSSELL2000"
+    MARKET_WIDE = "MARKET_WIDE"
+
+    @property
+    def label(self) -> str:
+        """Return the concise name used in user-facing summaries."""
+
+        return {
+            ExposureFamily.SP500: "S&P 500",
+            ExposureFamily.NASDAQ100: "Nasdaq-100",
+            ExposureFamily.RUSSELL2000: "Russell 2000",
+            ExposureFamily.MARKET_WIDE: "Broad market",
+        }[self]
+
+
+class IdentityStatus(str, Enum):
+    ACCEPTED = "accepted"
+    AMBIGUOUS = "ambiguous"
+    REJECTED = "rejected"
+    UNRESOLVED = "unresolved"
+
+
+class EvidenceStatus(str, Enum):
+    ACCEPTED = "accepted"
+    UNRESOLVED = "unresolved"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True, slots=True)
+class Article:
+    article_id: str
+    timestamp: datetime | str
+    text: str
+    source: str = "unknown"
+    content_id: str | None = None
+    decision_bucket: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.article_id.strip():
+            raise ValueError("article_id must be non-empty")
+        if not isinstance(self.text, str) or not self.text.strip():
+            raise ValueError("text must be a non-empty string")
+        object.__setattr__(self, "timestamp", parse_article_time(self.timestamp))
+        object.__setattr__(self, "content_id", self.content_id or self.article_id)
+
+
+@dataclass(frozen=True, slots=True)
+class Observation:
+    observation_id: str
+    article_id: str
+    matched_surface: str
+    span_start: int
+    span_end: int
+    entity_concept: str
+    detection_method: str
+    confidence: float | None = None
+    candidate_canonical_id: str | None = None
+    catalog_entry_id: str | None = None
+    catalog_version: str | None = None
+    rule_id: str | None = None
+    tag_type: str | None = None
+    event_family: str | None = None
+    market_wide_authorized: bool = False
+    context_status: str = "not_required"
+    source_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.span_start < 0 or self.span_end <= self.span_start:
+            raise ValueError("observation offsets must describe a non-empty span")
+        if not self.observation_id or not self.article_id or not self.matched_surface:
+            raise ValueError("observation identity and surface must be non-empty")
+        if self.confidence is not None and not 0 <= self.confidence <= 1:
+            raise ValueError("confidence must be in [0, 1]")
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationBundle:
+    article: Article
+    observations: tuple[Observation, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class IdentityResolution:
+    resolution_id: str
+    observation_id: str
+    article_id: str
+    status: IdentityStatus
+    canonical_id: str | None
+    reason_code: str
+    resolution_method: str
+    catalog_version: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.status is IdentityStatus.ACCEPTED and not self.canonical_id:
+            raise ValueError("accepted identities require a canonical_id")
+        if self.status is not IdentityStatus.ACCEPTED and self.canonical_id is not None:
+            raise ValueError("only accepted identities may assign canonical_id")
+
+
+@dataclass(frozen=True, slots=True)
+class EvidencePath:
+    evidence_id: str
+    article_id: str
+    tag_type: str
+    tag_detail: str
+    matched_surface: str
+    detection_method: str
+    status: EvidenceStatus
+    link_status: str
+    target_id: str | None
+    exposure_family: ExposureFamily | None
+    reason_code: str
+    tier: int
+    observation_ids: tuple[str, ...] = ()
+    identity_resolution_ids: tuple[str, ...] = ()
+    relationship_ids: tuple[str, ...] = ()
+    catalog_version: str | None = None
+    event_family: str | None = None
+    explicit_market_wide_rule: bool = False
+
+    def __post_init__(self) -> None:
+        if self.tier < 0:
+            raise ValueError("evidence tier must be non-negative")
+        if self.status is EvidenceStatus.ACCEPTED and self.exposure_family is None:
+            raise ValueError("accepted exposure evidence requires an exposure family")
+        if self.link_status == "resolved_exposure" and not self.relationship_ids:
+            raise ValueError("resolved exposure evidence requires relationship lineage")
+        if self.exposure_family is ExposureFamily.MARKET_WIDE and (
+            self.link_status != "market_wide" or not self.explicit_market_wide_rule
+        ):
+            raise ValueError("MARKET_WIDE requires an explicitly authorized rule")
+
+
+@dataclass(frozen=True, slots=True)
+class ArticleAdmissibilityDecision:
+    article_id: str
+    status: ArticleAdmissibilityStatus
+    accepted_evidence: tuple[EvidencePath, ...] = ()
+    unresolved_evidence: tuple[EvidencePath, ...] = ()
+    rejected_evidence: tuple[EvidencePath, ...] = ()
+    reason_codes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ExposureRelevanceDecision:
+    article_id: str
+    exposure_family: ExposureFamily
+    status: ExposureRelevanceStatus
+    evidence_paths: tuple[EvidencePath, ...] = ()
+    unresolved_paths: tuple[EvidencePath, ...] = ()
+    reason_codes: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.status is ExposureRelevanceStatus.SUPPORTED and not self.evidence_paths:
+            raise ValueError("supported exposure decisions require evidence lineage")
+        if (
+            self.status is ExposureRelevanceStatus.PLAUSIBLE_UNRESOLVED
+            and not self.unresolved_paths
+        ):
+            raise ValueError(
+                "plausible unresolved exposure decisions require unresolved evidence"
+            )
+        if any(
+            path.exposure_family is not self.exposure_family
+            for path in self.evidence_paths
+        ):
+            raise ValueError("evidence paths must support the decision exposure family")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class RelevanceDecision:
+    article: Article
+    article_decision: ArticleAdmissibilityDecision
+    exposure_decisions: Mapping[ExposureFamily, ExposureRelevanceDecision]
+    observations: tuple[Observation, ...] = ()
+    resolutions: tuple[IdentityResolution, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.article.article_id != self.article_decision.article_id:
+            raise ValueError("article decision provenance mismatch")
+        decisions = dict(self.exposure_decisions)
+        if any(key is not value.exposure_family for key, value in decisions.items()):
+            raise ValueError("exposure decision mapping keys must match their values")
+
+        observation_ids = {row.observation_id for row in self.observations}
+        if len(observation_ids) != len(self.observations):
+            raise ValueError("observation IDs must be unique")
+        if any(row.article_id != self.article.article_id for row in self.observations):
+            raise ValueError("observation provenance mismatch")
+
+        resolution_ids = {row.resolution_id for row in self.resolutions}
+        if len(resolution_ids) != len(self.resolutions):
+            raise ValueError("identity resolution IDs must be unique")
+        for resolution in self.resolutions:
+            if resolution.article_id != self.article.article_id:
+                raise ValueError("identity resolution provenance mismatch")
+            if resolution.observation_id not in observation_ids:
+                raise ValueError(
+                    "identity resolution references an unknown observation"
+                )
+
+        article_paths = (
+            *self.article_decision.accepted_evidence,
+            *self.article_decision.unresolved_evidence,
+            *self.article_decision.rejected_evidence,
+        )
+        exposure_paths = tuple(
+            path
+            for decision in decisions.values()
+            for path in (*decision.evidence_paths, *decision.unresolved_paths)
+        )
+        for path in (*article_paths, *exposure_paths):
+            if path.article_id != self.article.article_id:
+                raise ValueError("evidence path provenance mismatch")
+            if not set(path.observation_ids).issubset(observation_ids):
+                raise ValueError("evidence path references an unknown observation")
+            if not set(path.identity_resolution_ids).issubset(resolution_ids):
+                raise ValueError(
+                    "evidence path references an unknown identity resolution"
+                )
+        object.__setattr__(self, "exposure_decisions", MappingProxyType(decisions))
+
+    @property
+    def status(self) -> str:
+        """Return the plain-language overall result."""
+
+        return {
+            ArticleAdmissibilityStatus.ACCEPTED: "relevant",
+            ArticleAdmissibilityStatus.PLAUSIBLE_UNRESOLVED: "needs_review",
+            ArticleAdmissibilityStatus.REJECTED: "not_relevant",
+        }[self.article_decision.status]
+
+    @property
+    def accepted(self) -> bool:
+        """Whether the article has accepted financial evidence."""
+
+        return self.article_decision.status is ArticleAdmissibilityStatus.ACCEPTED
+
+    @property
+    def relevant_to(self) -> tuple[str, ...]:
+        """Plain-language markets with a completed relevance path."""
+
+        return tuple(
+            family.label
+            for family in ExposureFamily
+            if (
+                (result := self.exposure_decisions.get(family)) is not None
+                and result.status is ExposureRelevanceStatus.SUPPORTED
+            )
+        )
+
+    @staticmethod
+    def _surface(path: EvidencePath) -> str:
+        surface = " ".join(path.matched_surface.split())
+        return surface if len(surface) <= 60 else surface[:57].rstrip() + "..."
+
+    @classmethod
+    def _why_for_path(cls, path: EvidencePath) -> str:
+        surface = cls._surface(path)
+        if path.link_status == "resolved_exposure" and path.exposure_family:
+            return f"{surface} connects to {path.exposure_family.label}"
+        if path.link_status == "direct_asset":
+            return f"fund or ticker found: {surface}"
+        if path.link_status == "direct_benchmark":
+            return f"index or benchmark found: {surface}"
+        if path.link_status == "market_wide":
+            return f"broad-market news found: {surface}"
+        return {
+            "macroeconomic_indicator": f"economic indicator found: {surface}",
+            "financial_regulator": f"financial regulator found: {surface}",
+            "sector_or_industry": f"industry or sector found: {surface}",
+            "company_event": f"company event found: {surface}",
+        }.get(path.tag_type, f"financial information found: {surface}")
+
+    @property
+    def why(self) -> str:
+        """Return a short explanation; detailed lineage remains available separately."""
+
+        if self.article_decision.status is ArticleAdmissibilityStatus.REJECTED:
+            return "No financial match found."
+
+        paths = (
+            self.article_decision.accepted_evidence
+            if self.article_decision.status is ArticleAdmissibilityStatus.ACCEPTED
+            else self.article_decision.unresolved_evidence
+        )
+        phrases: list[str] = []
+        seen: set[str] = set()
+        for path in sorted(
+            paths,
+            key=lambda item: (
+                item.tier,
+                item.matched_surface.casefold(),
+                item.evidence_id,
+            ),
+        ):
+            key = path.matched_surface.casefold().strip()
+            if key in seen:
+                continue
+            seen.add(key)
+            phrases.append(self._why_for_path(path))
+
+        if not phrases:
+            return (
+                "Possible financial information was found, but it needs review."
+                if self.status == "needs_review"
+                else "Financial information found."
+            )
+        visible = phrases[:3]
+        reason = "; ".join(visible)
+        if len(phrases) > len(visible):
+            reason += f"; and {len(phrases) - len(visible)} more match(es)"
+        if self.status == "needs_review":
+            reason += ", but it could not be connected to a configured market"
+        return reason[0].upper() + reason[1:] + "."
+
+    def summary(self) -> dict[str, object]:
+        """Return the small, JSON-friendly result most callers need."""
+
+        return {
+            "article_id": self.article.article_id,
+            "status": self.status,
+            "accepted": self.accepted,
+            "why": self.why,
+            "relevant_to": list(self.relevant_to),
+        }
+
+    def __repr__(self) -> str:
+        return (
+            "RelevanceDecision("
+            f"article_id={self.article.article_id!r}, "
+            f"status={self.status!r}, "
+            f"relevant_to={self.relevant_to!r}, "
+            f"why={self.why!r})"
+        )
+
+    def _repr_markdown_(self) -> str:
+        """Render a concise decision card in Jupyter without an IPython dependency."""
+
+        def markdown(value: object) -> str:
+            escaped = html.escape(str(value))
+            for character in ("\\", "`", "*", "_", "[", "]"):
+                escaped = escaped.replace(character, f"\\{character}")
+            return escaped
+
+        heading = {
+            "relevant": "Keep",
+            "needs_review": "Check",
+            "not_relevant": "Ignore",
+        }[self.status]
+        lines = [f"### {heading}", "", f"**Why:** {markdown(self.why)}"]
+        if self.relevant_to:
+            lines.extend(("", f"**Markets:** {', '.join(self.relevant_to)}"))
+        lines.extend(
+            (
+                "",
+                (
+                    f"*{markdown(self.article.source)} | "
+                    f"{markdown(self.article.timestamp.isoformat())} | "
+                    f"{markdown(self.article.article_id)}*"
+                ),
+            )
+        )
+        return "\n".join(lines)
+
+
+@dataclass(frozen=True, slots=True)
+class RankedCandidate:
+    decision_bucket: str
+    exposure_family: ExposureFamily
+    rank: int
+    article_id: str
+    accepted_evidence_ids: tuple[str, ...]
+    decision: RelevanceDecision = field(compare=False, repr=False)

src/range_news/_taxonomy_impl.py

@@ -0,0 +1,629 @@
+"""Immutable taxonomy composition and deterministic ranking contracts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field, fields, is_dataclass, replace
+from datetime import datetime, timezone
+from enum import Enum
+from importlib.resources import files as resource_files
+from pathlib import Path
+from types import MappingProxyType
+
+from ._core.catalogs import (
+    CatalogAlias,
+    CatalogBundle,
+    CatalogEntity,
+    LexicalRule,
+    active_during,
+    load_catalogs,
+)
+from ._core.config import NewsRelevanceConfig, load_config
+from ._core.models import (
+    EvidencePath,
+    ExposureFamily,
+    ExposureRelevanceStatus,
+    RankedCandidate,
+    RelevanceDecision,
+)
+
+_MATCH_MODES = {
+    "exact_identifier",
+    "exact_case_sensitive",
+    "exact_casefold",
+    "normalized_phrase",
+}
+_ENTITY_KINDS = {"fund", "index", "issuer_family"}
+_DETECTION_METHODS = {"lexical_phrase", "event_rule"}
+
+
+def _key(value: object) -> str:
+    if isinstance(value, Enum):
+        return str(value.value)
+    return str(value)
+
+
+def _stable_value(value: object) -> object:
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return value.name
+    if is_dataclass(value):
+        return {
+            item.name: _stable_value(getattr(value, item.name))
+            for item in fields(value)
+        }
+    if isinstance(value, Mapping):
+        return {
+            _key(key): _stable_value(item)
+            for key, item in sorted(value.items(), key=lambda pair: _key(pair[0]))
+        }
+    if isinstance(value, (set, frozenset)):
+        return sorted((_stable_value(item) for item in value), key=repr)
+    if isinstance(value, (tuple, list)):
+        return [_stable_value(item) for item in value]
+    return value
+
+
+def _fingerprint(config: NewsRelevanceConfig, catalogs: CatalogBundle) -> str:
+    config_payload = {
+        item.name: _stable_value(getattr(config, item.name))
+        for item in fields(config)
+        if item.name not in {"entity_catalog_path", "lexical_catalog_path"}
+    }
+    payload = {
+        "config": config_payload,
+        "catalogs": _stable_value(catalogs),
+    }
+    encoded = json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def copy_default_taxonomy(
+    destination: str | Path,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Copy an editable default taxonomy bundle and return its config path.
+
+    The resulting directory contains ``taxonomy.yml`` plus the two catalog
+    files it references. Call :meth:`Taxonomy.from_yaml` or
+    :meth:`RelevanceEngine.from_yaml` after editing the copies.
+    """
+
+    root = Path(destination).expanduser().resolve()
+    package = resource_files("range_news._core")
+    copies = (
+        (package.joinpath("configs", "default.yml"), root / "taxonomy.yml"),
+        (
+            package.joinpath("catalogs", "entities.yml"),
+            root / "catalogs" / "entities.yml",
+        ),
+        (
+            package.joinpath("catalogs", "lexical.yml"),
+            root / "catalogs" / "lexical.yml",
+        ),
+    )
+    existing = [target for _source, target in copies if target.exists()]
+    if existing and not overwrite:
+        names = ", ".join(str(path) for path in existing)
+        raise FileExistsError(
+            f"taxonomy files already exist: {names}; pass overwrite=True to replace them"
+        )
+
+    for source, target in copies:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(source.read_bytes())
+    return root / "taxonomy.yml"
+
+
+def _validate(config: NewsRelevanceConfig, catalogs: CatalogBundle) -> None:
+    if not isinstance(config, NewsRelevanceConfig):
+        raise TypeError("config must be a NewsRelevanceConfig")
+    if not isinstance(catalogs, CatalogBundle):
+        raise TypeError("catalogs must be a CatalogBundle")
+
+    for canonical_id, entity in catalogs.entities.items():
+        if canonical_id != entity.canonical_id:
+            raise ValueError(
+                f"entity mapping key {canonical_id!r} does not match "
+                f"canonical ID {entity.canonical_id!r}"
+            )
+        for name, value in (
+            ("canonical_id", entity.canonical_id),
+            ("canonical_name", entity.canonical_name),
+            ("entity_concept", entity.entity_concept),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"entity {canonical_id!r} has empty {name}")
+        if entity.entity_kind not in _ENTITY_KINDS:
+            raise ValueError(
+                f"entity {canonical_id!r} has unsupported kind "
+                f"{entity.entity_kind!r}"
+            )
+        active_during(
+            entity.valid_from,
+            valid_from=entity.valid_from,
+            valid_to=entity.valid_to,
+        )
+
+    alias_ids: set[str] = set()
+    for alias in catalogs.aliases:
+        if not isinstance(alias.alias_id, str) or not alias.alias_id.strip():
+            raise ValueError("alias ID must be a non-empty string")
+        if not isinstance(alias.surface, str) or not alias.surface.strip():
+            raise ValueError(f"alias {alias.alias_id!r} has an empty surface")
+        if alias.alias_id in alias_ids:
+            raise ValueError(f"duplicate alias ID: {alias.alias_id}")
+        alias_ids.add(alias.alias_id)
+        if alias.canonical_id not in catalogs.entities:
+            raise ValueError(
+                f"alias {alias.alias_id!r} references unknown entity "
+                f"{alias.canonical_id!r}"
+            )
+        if alias.match_mode not in _MATCH_MODES:
+            raise ValueError(
+                f"alias {alias.alias_id!r} has unsupported match mode "
+                f"{alias.match_mode!r}"
+            )
+        if alias.requires_context and alias.context_rule_id not in config.context_rules:
+            raise ValueError(
+                f"alias {alias.alias_id!r} requires unknown context rule "
+                f"{alias.context_rule_id!r}"
+            )
+        active_during(
+            alias.valid_from,
+            valid_from=alias.valid_from,
+            valid_to=alias.valid_to,
+        )
+
+    rule_ids: set[str] = set()
+    for rule in catalogs.lexical_rules:
+        if not isinstance(rule.rule_id, str) or not rule.rule_id.strip():
+            raise ValueError("lexical rule ID must be a non-empty string")
+        if rule.rule_id in rule_ids:
+            raise ValueError(f"duplicate lexical rule ID: {rule.rule_id}")
+        rule_ids.add(rule.rule_id)
+        if not rule.phrases or any(
+            not isinstance(phrase, str) or not phrase.strip() for phrase in rule.phrases
+        ):
+            raise ValueError(
+                f"lexical rule {rule.rule_id!r} needs non-empty string phrases"
+            )
+        if rule.detection_method not in _DETECTION_METHODS:
+            raise ValueError(
+                f"lexical rule {rule.rule_id!r} has unsupported detection method "
+                f"{rule.detection_method!r}"
+            )
+        if rule.tag_type not in config.ranking_tiers:
+            raise ValueError(
+                f"lexical tag type {rule.tag_type!r} has no configured ranking tier"
+            )
+        if (
+            isinstance(rule.context_window_chars, bool)
+            or not isinstance(rule.context_window_chars, int)
+            or rule.context_window_chars < 0
+        ):
+            raise ValueError(
+                f"lexical rule {rule.rule_id!r} has an invalid context window"
+            )
+
+    memberships: dict[str, ExposureFamily] = {}
+    for family, members in config.exposure_members.items():
+        if not isinstance(family, ExposureFamily):
+            raise ValueError(f"unsupported exposure family: {family!r}")
+        for canonical_id in members:
+            if canonical_id not in catalogs.entities:
+                raise ValueError(
+                    f"exposure family {family.value} references unknown entity "
+                    f"{canonical_id!r}"
+                )
+            previous = memberships.setdefault(canonical_id, family)
+            if previous is not family:
+                raise ValueError(
+                    f"entity {canonical_id!r} belongs to both {previous.value} "
+                    f"and {family.value}"
+                )
+
+
+@dataclass(frozen=True, slots=True)
+class Taxonomy:
+    """A validated, immutable configuration and catalog bundle."""
+
+    config: NewsRelevanceConfig
+    catalogs: CatalogBundle
+    fingerprint: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        _validate(self.config, self.catalogs)
+        object.__setattr__(
+            self, "fingerprint", _fingerprint(self.config, self.catalogs)
+        )
+
+    @property
+    def version(self) -> str:
+        """Return the version of the decision configuration."""
+
+        return self.config.version
+
+    @property
+    def entity_ids(self) -> tuple[str, ...]:
+        """Return canonical entity identifiers in stable order."""
+
+        return tuple(sorted(self.catalogs.entities))
+
+    @property
+    def lexical_rule_ids(self) -> tuple[str, ...]:
+        """Return lexical rule identifiers in stable order."""
+
+        return tuple(sorted(rule.rule_id for rule in self.catalogs.lexical_rules))
+
+    def describe(self) -> dict[str, object]:
+        """Return a compact, serializable summary of this taxonomy."""
+
+        return {
+            "version": self.version,
+            "fingerprint": self.fingerprint,
+            "entity_catalog_version": self.catalogs.entity_catalog_version,
+            "lexical_catalog_version": self.catalogs.lexical_catalog_version,
+            "entities": len(self.catalogs.entities),
+            "aliases": len(self.catalogs.aliases),
+            "relationships": len(self.catalogs.relationships),
+            "lexical_rules": len(self.catalogs.lexical_rules),
+            "exposure_families": tuple(family.value for family in ExposureFamily),
+        }
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> "Taxonomy":
+        """Load a full maintained news-relevance configuration file."""
+
+        config = load_config(path)
+        return Taxonomy(config=config, catalogs=load_catalogs(config))
+
+    def extend(
+        self,
+        configure: Callable[["TaxonomyBuilder"], object],
+    ) -> "Taxonomy":
+        """Return a new taxonomy after applying one builder callback."""
+
+        if not callable(configure):
+            raise TypeError("configure must be callable")
+        builder = TaxonomyBuilder(self)
+        configure(builder)
+        return builder.build()
+
+
+class DefaultTaxonomy(Taxonomy):
+    """The bundled financial taxonomy, optionally extended by `configure()`."""
+
+    def __init__(self) -> None:
+        config = load_config()
+        catalogs = load_catalogs(config)
+        builder = TaxonomyBuilder._from_parts(config, catalogs)
+        self.configure(builder)
+        built = builder.build()
+        super().__init__(config=built.config, catalogs=built.catalogs)
+
+    def configure(self, builder: "TaxonomyBuilder") -> None:
+        """Override in a subclass to add rules before the taxonomy is frozen."""
+
+
+class TaxonomyBuilder:
+    """Mutable construction surface whose `build()` result is immutable."""
+
+    __slots__ = (
+        "_aliases",
+        "_catalogs",
+        "_changed_entities",
+        "_changed_lexical",
+        "_config",
+        "_entities",
+        "_exposure_members",
+        "_lexical_rules",
+    )
+
+    def __init__(self, base: Taxonomy) -> None:
+        if not isinstance(base, Taxonomy):
+            raise TypeError("base must be a Taxonomy")
+        self._initialize(base.config, base.catalogs)
+
+    @classmethod
+    def _from_parts(
+        cls,
+        config: NewsRelevanceConfig,
+        catalogs: CatalogBundle,
+    ) -> "TaxonomyBuilder":
+        builder = cls.__new__(cls)
+        builder._initialize(config, catalogs)
+        return builder
+
+    def _initialize(
+        self,
+        config: NewsRelevanceConfig,
+        catalogs: CatalogBundle,
+    ) -> None:
+        self._config = config
+        self._catalogs = catalogs
+        self._entities = dict(catalogs.entities)
+        self._aliases = list(catalogs.aliases)
+        self._lexical_rules = list(catalogs.lexical_rules)
+        self._exposure_members = {
+            family: set(members) for family, members in config.exposure_members.items()
+        }
+        self._changed_entities = False
+        self._changed_lexical = False
+
+    def add_entity(
+        self,
+        *,
+        canonical_id: str,
+        canonical_name: str,
+        entity_concept: str,
+        entity_kind: str,
+        valid_from: str,
+        valid_to: str | None = None,
+        exposure_family: ExposureFamily | str | None = None,
+    ) -> "TaxonomyBuilder":
+        if not canonical_id.strip() or canonical_id in self._entities:
+            raise ValueError(f"entity ID must be new and non-empty: {canonical_id!r}")
+        if entity_kind not in _ENTITY_KINDS:
+            raise ValueError(f"unsupported entity kind: {entity_kind!r}")
+        entity = CatalogEntity(
+            canonical_id=canonical_id,
+            canonical_name=canonical_name,
+            entity_concept=entity_concept,
+            entity_kind=entity_kind,
+            valid_from=valid_from,
+            valid_to=valid_to,
+        )
+        self._entities[canonical_id] = entity
+        if exposure_family is not None:
+            family = ExposureFamily(exposure_family)
+            self._exposure_members.setdefault(family, set()).add(canonical_id)
+        self._changed_entities = True
+        return self
+
+    def add_alias(
+        self,
+        *,
+        alias_id: str,
+        canonical_id: str,
+        surface: str,
+        match_mode: str = "normalized_phrase",
+        requires_context: bool = False,
+        context_rule_id: str | None = None,
+        valid_from: str | None = None,
+        valid_to: str | None = None,
+        source_id: str = "user-taxonomy",
+    ) -> "TaxonomyBuilder":
+        if any(row.alias_id == alias_id for row in self._aliases):
+            raise ValueError(f"duplicate alias ID: {alias_id}")
+        entity = self._entities.get(canonical_id)
+        if entity is None:
+            raise ValueError(f"alias references unknown entity: {canonical_id}")
+        if match_mode not in _MATCH_MODES:
+            raise ValueError(f"unsupported match mode: {match_mode!r}")
+        if requires_context and context_rule_id not in self._config.context_rules:
+            raise ValueError(f"unknown context rule: {context_rule_id!r}")
+        self._aliases.append(
+            CatalogAlias(
+                alias_id=alias_id,
+                canonical_id=canonical_id,
+                surface=surface,
+                match_mode=match_mode,
+                requires_context=requires_context,
+                context_rule_id=context_rule_id if requires_context else None,
+                valid_from=valid_from or entity.valid_from,
+                valid_to=valid_to if valid_to is not None else entity.valid_to,
+                source_id=source_id,
+            )
+        )
+        self._changed_entities = True
+        return self
+
+    def add_lexical_rule(
+        self,
+        *,
+        rule_id: str,
+        entity_concept: str,
+        tag_type: str,
+        phrases: Sequence[str],
+        target_id: str | None = None,
+        detection_method: str = "lexical_phrase",
+        market_wide_authorized: bool = False,
+        case_sensitive: bool = False,
+        context_window_chars: int = 160,
+        context_any: Sequence[str] = (),
+        event_family: str | None = None,
+        source_id: str = "user-taxonomy",
+    ) -> "TaxonomyBuilder":
+        if any(row.rule_id == rule_id for row in self._lexical_rules):
+            raise ValueError(f"duplicate lexical rule ID: {rule_id}")
+        if detection_method not in _DETECTION_METHODS:
+            raise ValueError(f"unsupported detection method: {detection_method!r}")
+        if tag_type not in self._config.ranking_tiers:
+            raise ValueError(
+                f"lexical tag type {tag_type!r} has no configured ranking tier"
+            )
+        if isinstance(phrases, (str, bytes)):
+            raise TypeError("phrases must be a sequence of strings, not one string")
+        phrase_tuple = tuple(phrases)
+        if not phrase_tuple or any(
+            not isinstance(item, str) or not item.strip() for item in phrase_tuple
+        ):
+            raise ValueError("phrases must contain non-empty strings")
+        if (
+            isinstance(context_window_chars, bool)
+            or not isinstance(context_window_chars, int)
+            or context_window_chars < 0
+        ):
+            raise ValueError("context_window_chars must be non-negative")
+        if isinstance(context_any, (str, bytes)) or any(
+            not isinstance(item, str) or not item.strip() for item in context_any
+        ):
+            raise ValueError("context_any must contain non-empty strings")
+        self._lexical_rules.append(
+            LexicalRule(
+                rule_id=rule_id,
+                entity_concept=entity_concept,
+                tag_type=tag_type,
+                target_id=target_id,
+                phrases=phrase_tuple,
+                detection_method=detection_method,
+                market_wide_authorized=market_wide_authorized,
+                case_sensitive=case_sensitive,
+                context_window_chars=context_window_chars,
+                context_any=tuple(context_any),
+                event_family=event_family,
+                source_id=source_id,
+            )
+        )
+        self._changed_lexical = True
+        return self
+
+    def build(self) -> Taxonomy:
+        exposure_members = MappingProxyType(
+            {
+                family: frozenset(members)
+                for family, members in self._exposure_members.items()
+            }
+        )
+        config = replace(self._config, exposure_members=exposure_members)
+        entity_version = self._catalogs.entity_catalog_version
+        lexical_version = self._catalogs.lexical_catalog_version
+        if self._changed_entities and not entity_version.endswith("+custom"):
+            entity_version += "+custom"
+        if self._changed_lexical and not lexical_version.endswith("+custom"):
+            lexical_version += "+custom"
+        catalogs = CatalogBundle(
+            entity_catalog_version=entity_version,
+            lexical_catalog_version=lexical_version,
+            entities=MappingProxyType(dict(self._entities)),
+            aliases=tuple(self._aliases),
+            relationships=MappingProxyType(dict(self._catalogs.relationships)),
+            lexical_rules=tuple(self._lexical_rules),
+        )
+        return Taxonomy(config=config, catalogs=catalogs)
+
+
+class Ranker(ABC):
+    """Stable ranking template; subclasses only define the domain sort key."""
+
+    @abstractmethod
+    def sort_key(
+        self,
+        prediction: RelevanceDecision,
+        accepted_paths: tuple[EvidencePath, ...],
+        *,
+        exposure_family: ExposureFamily,
+        decision_bucket: str,
+    ) -> tuple[object, ...]:
+        """Return an ascending key; article ID is appended as the final tie-break."""
+
+    def rank(
+        self,
+        predictions: Iterable[RelevanceDecision],
+        *,
+        config: NewsRelevanceConfig,
+        exposure_family: ExposureFamily | str,
+        decision_bucket: datetime | str,
+        limit: int | None = None,
+    ) -> tuple[RankedCandidate, ...]:
+        if limit is not None and (
+            isinstance(limit, bool) or not isinstance(limit, int) or limit <= 0
+        ):
+            raise ValueError("limit must be a positive integer or None")
+        family = ExposureFamily(exposure_family)
+        bucket = str(decision_bucket)
+        grouped: dict[str, tuple[RelevanceDecision, list[EvidencePath]]] = {}
+        for prediction in predictions:
+            exposure = prediction.exposure_decisions.get(family)
+            if (
+                exposure is None
+                or exposure.status is not ExposureRelevanceStatus.SUPPORTED
+            ):
+                continue
+            paths = [
+                path
+                for path in exposure.evidence_paths
+                if path.status.value == "accepted"
+                and path.link_status in config.accepted_link_statuses
+            ]
+            if not paths:
+                continue
+            existing = grouped.get(prediction.article.article_id)
+            if existing is not None and existing[0] is not prediction:
+                raise ValueError("one article ID cannot map to multiple predictions")
+            if existing is None:
+                grouped[prediction.article.article_id] = (prediction, paths)
+            else:
+                existing[1].extend(paths)
+
+        sortable = []
+        for article_id, (prediction, paths) in grouped.items():
+            accepted = tuple(paths)
+            custom = self.sort_key(
+                prediction,
+                accepted,
+                exposure_family=family,
+                decision_bucket=bucket,
+            )
+            if not isinstance(custom, tuple):
+                raise TypeError("Ranker.sort_key() must return a tuple")
+            sortable.append(((custom, article_id), prediction, accepted))
+
+        ordered = sorted(sortable, key=lambda row: row[0])
+        if limit is not None:
+            ordered = ordered[:limit]
+        return tuple(
+            RankedCandidate(
+                decision_bucket=bucket,
+                exposure_family=family,
+                rank=index,
+                article_id=prediction.article.article_id,
+                accepted_evidence_ids=tuple(
+                    sorted(path.evidence_id for path in accepted)
+                ),
+                decision=prediction,
+            )
+            for index, (_key_row, prediction, accepted) in enumerate(ordered, 1)
+        )
+
+
+class DefaultRanker(Ranker):
+    """The maintained tier, evidence-diversity, recency ordering."""
+
+    def sort_key(
+        self,
+        prediction: RelevanceDecision,
+        accepted_paths: tuple[EvidencePath, ...],
+        *,
+        exposure_family: ExposureFamily,
+        decision_bucket: str,
+    ) -> tuple[object, ...]:
+        del exposure_family, decision_bucket
+        timestamp = prediction.article.timestamp.astimezone(timezone.utc).timestamp()
+        return (
+            min(path.tier for path in accepted_paths),
+            -len({path.tag_detail for path in accepted_paths}),
+            -len({path.detection_method for path in accepted_paths}),
+            -timestamp,
+        )
+
+
+__all__ = [
+    "DefaultRanker",
+    "DefaultTaxonomy",
+    "Ranker",
+    "Taxonomy",
+    "TaxonomyBuilder",
+    "copy_default_taxonomy",
+]

src/range_news/api.py

@@ -0,0 +1,371 @@
+"""Public API for deterministic financial-news relevance screening."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from collections.abc import Iterable, Sequence
+from datetime import datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from ._core.accelerated.indicator import AcceleratedRelevanceIndicator
+from ._core.accelerated.compact import (
+    ArrowCompactFacts,
+    ColumnArticleBatch,
+    CompactRelevanceIndicator,
+)
+from ._core.models import Article, ExposureFamily, RelevanceDecision
+
+from .backends import available_backends, create_backend
+from .customization import (
+    DefaultRanker,
+    DefaultTaxonomy,
+    Ranker,
+    Taxonomy,
+)
+from .models import (
+    BackendInfo,
+    Prediction,
+    PythonScreeningBatch,
+    RankedPrediction,
+)
+
+TimestampLike = datetime | str
+
+
+def _workers(value: int | None) -> int:
+    if value is None:
+        return max(1, min(10, os.cpu_count() or 1))
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError("workers must be a positive integer or None")
+    return value
+
+
+def _article_id(text: str, timestamp: TimestampLike) -> str:
+    payload = f"{timestamp}\0{text}".encode("utf-8")
+    return f"article-{hashlib.sha256(payload).hexdigest()[:20]}"
+
+
+def _optional_length(
+    name: str,
+    values: Sequence[object] | None,
+    expected: int,
+) -> None:
+    if values is not None and len(values) != expected:
+        raise ValueError(f"{name} length {len(values)} does not match {expected}")
+
+
+class RelevanceEngine:
+    """Exact rich prediction plus explicitly separate compact screening paths."""
+
+    __slots__ = (
+        "_backend",
+        "_indicator",
+        "_ranker",
+        "_screening_indicator",
+        "_taxonomy",
+        "_workers",
+    )
+
+    def __init__(
+        self,
+        taxonomy: Taxonomy | None = None,
+        *,
+        ranker: Ranker | None = None,
+        backend: Literal["cpu"] = "cpu",
+        workers: int | None = None,
+    ) -> None:
+        resolved_taxonomy = taxonomy or DefaultTaxonomy()
+        if not isinstance(resolved_taxonomy, Taxonomy):
+            raise TypeError("taxonomy must be a Taxonomy or None")
+        resolved_ranker = ranker or DefaultRanker()
+        if not isinstance(resolved_ranker, Ranker):
+            raise TypeError("ranker must inherit Ranker")
+        self._taxonomy = resolved_taxonomy
+        self._ranker = resolved_ranker
+        self._workers = _workers(workers)
+        self._backend = create_backend(backend)
+        self._indicator = AcceleratedRelevanceIndicator(
+            config=resolved_taxonomy.config,
+            catalogs=resolved_taxonomy.catalogs,
+        )
+        self._screening_indicator = CompactRelevanceIndicator(
+            config=resolved_taxonomy.config,
+            catalogs=resolved_taxonomy.catalogs,
+        )
+
+    @classmethod
+    def from_yaml(
+        cls,
+        path: str | Path,
+        *,
+        ranker: Ranker | None = None,
+        backend: Literal["cpu"] = "cpu",
+        workers: int | None = None,
+    ) -> "RelevanceEngine":
+        return cls(
+            Taxonomy.from_yaml(path),
+            ranker=ranker,
+            backend=backend,
+            workers=workers,
+        )
+
+    @property
+    def taxonomy(self) -> Taxonomy:
+        return self._taxonomy
+
+    @property
+    def ranker(self) -> Ranker:
+        return self._ranker
+
+    @property
+    def backend(self) -> str:
+        return self._backend.name
+
+    @property
+    def backend_info(self) -> BackendInfo:
+        return self._backend.describe(self._screening_indicator)
+
+    @property
+    def workers(self) -> int:
+        return self._workers
+
+    def predict(
+        self,
+        text: str,
+        *,
+        timestamp: TimestampLike,
+        article_id: str | None = None,
+        source: str = "unknown",
+    ) -> Prediction:
+        """Build one rich decision with evidence and explanation provenance."""
+
+        article = Article(
+            article_id=(
+                _article_id(text, timestamp) if article_id is None else article_id
+            ),
+            timestamp=timestamp,
+            text=text,
+            source=source,
+        )
+        return self._indicator.predict(article)
+
+    def predict_batch(
+        self,
+        texts: Sequence[str],
+        *,
+        timestamps: Sequence[TimestampLike],
+        article_ids: Sequence[str] | None = None,
+        sources: Sequence[str] | None = None,
+        workers: int | None = None,
+    ) -> tuple[Prediction, ...]:
+        """Build rich decisions; use `screen_batch()` for throughput work."""
+
+        count = len(texts)
+        if len(timestamps) != count:
+            raise ValueError("texts and timestamps must have equal lengths")
+        _optional_length("article_ids", article_ids, count)
+        _optional_length("sources", sources, count)
+        articles = tuple(
+            Article(
+                article_id=(
+                    article_ids[index] if article_ids is not None else f"row-{index}"
+                ),
+                timestamp=timestamps[index],
+                text=text,
+                source=sources[index] if sources is not None else "unknown",
+            )
+            for index, text in enumerate(texts)
+        )
+        return self._indicator.predict_batch(
+            articles,
+            workers=_workers(workers) if workers is not None else self._workers,
+        )
+
+    def screen_batch(
+        self,
+        texts: Sequence[str],
+        *,
+        timestamps: Sequence[TimestampLike],
+        article_ids: Sequence[str] | None = None,
+        sources: Sequence[str] | None = None,
+        workers: int | None = None,
+    ) -> PythonScreeningBatch:
+        """Run compact list screening with implicit zero-observation rows."""
+
+        count = len(texts)
+        if len(timestamps) != count:
+            raise ValueError("texts and timestamps must have equal lengths")
+        _optional_length("article_ids", article_ids, count)
+        _optional_length("sources", sources, count)
+        ids = (
+            article_ids
+            if article_ids is not None
+            else tuple(f"row-{index}" for index in range(count))
+        )
+        batch = ColumnArticleBatch(
+            article_ids=ids,
+            timestamps=timestamps,
+            texts=texts,
+            sources=sources,
+        )
+        return self._backend.screen_batch(
+            self._screening_indicator,
+            batch,
+            workers=_workers(workers) if workers is not None else self._workers,
+        )
+
+    def screen_arrow(
+        self,
+        data,
+        *,
+        text_column: str = "text",
+        timestamp_column: str = "timestamp",
+        workers: int | None = None,
+        row_count: int | None = None,
+    ) -> ArrowCompactFacts:
+        """Run the sparse Arrow path without materializing per-row Python objects."""
+
+        if row_count is not None and (
+            isinstance(row_count, bool)
+            or not isinstance(row_count, int)
+            or row_count < 0
+        ):
+            raise ValueError("row_count must be a non-negative integer or None")
+        discovered = getattr(data, "num_rows", None)
+        if discovered is not None:
+            discovered = int(discovered)
+            if row_count is None:
+                row_count = discovered
+            elif row_count != discovered:
+                raise ValueError(
+                    f"row_count {row_count} does not match Arrow rows {discovered}"
+                )
+
+        return self._backend.screen_arrow(
+            self._screening_indicator,
+            self._taxonomy,
+            data,
+            text_column=text_column,
+            timestamp_column=timestamp_column,
+            workers=_workers(workers) if workers is not None else self._workers,
+            row_count=row_count,
+        )
+
+    def explain(
+        self,
+        prediction: RelevanceDecision,
+        *,
+        format: Literal["text", "mermaid"] = "text",
+        detail: Literal["summary", "audit"] = "summary",
+    ) -> str:
+        """Format already-recorded evidence; this does not rerun prediction."""
+
+        if not isinstance(prediction, RelevanceDecision):
+            raise TypeError("prediction must be a rich Prediction")
+        if detail not in {"summary", "audit"}:
+            raise ValueError("detail must be 'summary' or 'audit'")
+        return self._indicator.explain(
+            prediction,
+            output_format=format,
+            detail=detail,
+        )
+
+    def rank(
+        self,
+        predictions: Iterable[Prediction],
+        *,
+        exposure_family: ExposureFamily | str,
+        decision_bucket: datetime | str,
+        limit: int | None = None,
+    ) -> tuple[RankedPrediction, ...]:
+        return self._ranker.rank(
+            predictions,
+            config=self._taxonomy.config,
+            exposure_family=exposure_family,
+            decision_bucket=decision_bucket,
+            limit=limit,
+        )
+
+
+@lru_cache(maxsize=1)
+def _default_engine() -> RelevanceEngine:
+    return RelevanceEngine()
+
+
+def predict(
+    text: str,
+    *,
+    timestamp: TimestampLike,
+    article_id: str | None = None,
+    source: str = "unknown",
+) -> Prediction:
+    return _default_engine().predict(
+        text,
+        timestamp=timestamp,
+        article_id=article_id,
+        source=source,
+    )
+
+
+def predict_batch(
+    texts: Sequence[str],
+    *,
+    timestamps: Sequence[TimestampLike],
+    article_ids: Sequence[str] | None = None,
+    sources: Sequence[str] | None = None,
+    workers: int | None = None,
+) -> tuple[Prediction, ...]:
+    return _default_engine().predict_batch(
+        texts,
+        timestamps=timestamps,
+        article_ids=article_ids,
+        sources=sources,
+        workers=workers,
+    )
+
+
+def screen_batch(
+    texts: Sequence[str],
+    *,
+    timestamps: Sequence[TimestampLike],
+    article_ids: Sequence[str] | None = None,
+    sources: Sequence[str] | None = None,
+    workers: int | None = None,
+) -> PythonScreeningBatch:
+    return _default_engine().screen_batch(
+        texts,
+        timestamps=timestamps,
+        article_ids=article_ids,
+        sources=sources,
+        workers=workers,
+    )
+
+
+def screen_arrow(
+    data,
+    *,
+    text_column: str = "text",
+    timestamp_column: str = "timestamp",
+    workers: int | None = None,
+    row_count: int | None = None,
+) -> ArrowCompactFacts:
+    return _default_engine().screen_arrow(
+        data,
+        text_column=text_column,
+        timestamp_column=timestamp_column,
+        workers=workers,
+        row_count=row_count,
+    )
+
+
+__all__ = [
+    "RelevanceEngine",
+    "available_backends",
+    "predict",
+    "predict_batch",
+    "screen_arrow",
+    "screen_batch",
+]

src/range_news/backends.py

@@ -0,0 +1,146 @@
+"""Backend selection for the supported CPU implementation."""
+
+from __future__ import annotations
+
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Protocol
+
+from ._core.accelerated.compact import (
+    ArrowCompactFacts,
+    ColumnArticleBatch,
+    CompactColumnScreenBatch,
+    CompactRelevanceIndicator,
+)
+from .models import BackendInfo
+
+if TYPE_CHECKING:
+    from .customization import Taxonomy
+
+
+def _native_available() -> bool:
+    try:
+        return find_spec("range_news._native") is not None
+    except (ImportError, ModuleNotFoundError, ValueError):
+        return False
+
+
+class _Backend(Protocol):
+    name: str
+
+    def describe(
+        self,
+        indicator: CompactRelevanceIndicator,
+    ) -> BackendInfo: ...
+
+    def screen_batch(
+        self,
+        indicator: CompactRelevanceIndicator,
+        batch: ColumnArticleBatch,
+        *,
+        workers: int,
+    ) -> CompactColumnScreenBatch: ...
+
+    def screen_arrow(
+        self,
+        indicator: CompactRelevanceIndicator,
+        taxonomy: "Taxonomy",
+        data,
+        *,
+        text_column: str,
+        timestamp_column: str,
+        workers: int,
+        row_count: int | None,
+    ) -> ArrowCompactFacts: ...
+
+
+class _CpuBackend:
+    name = "cpu"
+
+    def describe(
+        self,
+        indicator: CompactRelevanceIndicator,
+    ) -> BackendInfo:
+        native_list = indicator.list_available
+        native_arrow = indicator.arrow_available
+        if native_list and native_arrow:
+            detail = "Rust list and Arrow screening are available"
+        elif native_list:
+            detail = "Rust list screening is available; Arrow screening is unavailable"
+        else:
+            detail = (
+                "Python prediction is available; rebuild the native extension "
+                "for compact screening"
+            )
+        return BackendInfo(
+            name=self.name,
+            available=True,
+            accelerated=native_list,
+            detail=detail,
+        )
+
+    def screen_batch(
+        self,
+        indicator: CompactRelevanceIndicator,
+        batch: ColumnArticleBatch,
+        *,
+        workers: int,
+    ) -> CompactColumnScreenBatch:
+        if not indicator.list_available:
+            raise RuntimeError(
+                "Compact screening requires the packaged Rust extension; "
+                "install a wheel for this platform or rebuild the package"
+            )
+        return indicator.screen_column_batch(batch, workers=workers)
+
+    def screen_arrow(
+        self,
+        indicator: CompactRelevanceIndicator,
+        taxonomy: "Taxonomy",
+        data,
+        *,
+        text_column: str,
+        timestamp_column: str,
+        workers: int,
+        row_count: int | None,
+    ) -> ArrowCompactFacts:
+        del taxonomy
+        if not indicator.arrow_available:
+            raise RuntimeError(
+                "Arrow screening requires the packaged Rust extension and the "
+                "'arrow' extra"
+            )
+        return indicator.screen_arrow(
+            data,
+            text_column=text_column,
+            timestamp_column=timestamp_column,
+            workers=workers,
+            row_count=row_count,
+        )
+
+
+def create_backend(name: str) -> _Backend:
+    normalized = name.strip().lower() if isinstance(name, str) else ""
+    if normalized == "cpu":
+        return _CpuBackend()
+    raise ValueError("backend must be 'cpu'; experimental GPU backends are not shipped")
+
+
+def available_backends() -> tuple[BackendInfo, ...]:
+    """Return supported runtimes without initializing the native matcher."""
+
+    native = _native_available()
+    return (
+        BackendInfo(
+            name="cpu",
+            available=True,
+            accelerated=native,
+            detail=(
+                "packaged Rust extension is discoverable"
+                if native
+                else "Python prediction is available; native compact screening is unavailable"
+            ),
+        ),
+    )
+
+
+__all__ = ["available_backends", "create_backend"]

src/range_news/customization.py

@@ -0,0 +1,73 @@
+"""Public taxonomy composition and deterministic ranking contracts."""
+
+from __future__ import annotations
+
+from importlib.resources import files as resource_files
+from pathlib import Path
+
+from ._taxonomy_impl import (
+    DefaultRanker,
+    DefaultTaxonomy,
+    Ranker,
+    Taxonomy,
+    TaxonomyBuilder,
+)
+
+# Keep repr(), documentation, and pickling pointed at the public module after
+# the pre-release namespace migration.
+for _public_type in (
+    DefaultRanker,
+    DefaultTaxonomy,
+    Ranker,
+    Taxonomy,
+    TaxonomyBuilder,
+):
+    _public_type.__module__ = __name__
+
+
+class GeneralEconomyTaxonomy(DefaultTaxonomy):
+    """The bundled, conservative taxonomy for economy and broad-market news."""
+
+
+def copy_default_taxonomy(
+    destination: str | Path,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Copy the bundled general-economy taxonomy to an editable directory."""
+
+    root = Path(destination).expanduser().resolve()
+    package = resource_files("range_news._core")
+    copies = (
+        (package.joinpath("configs", "default.yml"), root / "taxonomy.yml"),
+        (
+            package.joinpath("catalogs", "entities.yml"),
+            root / "catalogs" / "entities.yml",
+        ),
+        (
+            package.joinpath("catalogs", "lexical.yml"),
+            root / "catalogs" / "lexical.yml",
+        ),
+    )
+    existing = [target for _source, target in copies if target.exists()]
+    if existing and not overwrite:
+        names = ", ".join(str(path) for path in existing)
+        raise FileExistsError(
+            f"taxonomy files already exist: {names}; pass overwrite=True to replace them"
+        )
+
+    for source, target in copies:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(source.read_bytes())
+    return root / "taxonomy.yml"
+
+
+__all__ = [
+    "DefaultRanker",
+    "DefaultTaxonomy",
+    "GeneralEconomyTaxonomy",
+    "Ranker",
+    "Taxonomy",
+    "TaxonomyBuilder",
+    "copy_default_taxonomy",
+]

src/range_news/models.py

@@ -0,0 +1,52 @@
+"""Public names for relevance inputs, decisions, and screening results."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._core.accelerated.compact import (
+    ArrowCompactFacts,
+    CompactColumnScreenBatch,
+    ScreeningResult,
+)
+from ._core.models import (
+    Article,
+    ArticleAdmissibilityStatus,
+    EvidencePath,
+    ExposureFamily,
+    ExposureRelevanceStatus,
+    RankedCandidate,
+    RelevanceDecision,
+)
+
+Prediction = RelevanceDecision
+RankedPrediction = RankedCandidate
+PythonScreeningBatch = CompactColumnScreenBatch
+ArrowScreeningBatch = ArrowCompactFacts
+ScreeningBatch = PythonScreeningBatch | ArrowScreeningBatch
+
+
+@dataclass(frozen=True, slots=True)
+class BackendInfo:
+    """Availability and acceleration details for one backend."""
+
+    name: str
+    available: bool
+    accelerated: bool
+    detail: str
+
+
+__all__ = [
+    "ArrowScreeningBatch",
+    "Article",
+    "ArticleAdmissibilityStatus",
+    "BackendInfo",
+    "EvidencePath",
+    "ExposureFamily",
+    "ExposureRelevanceStatus",
+    "Prediction",
+    "PythonScreeningBatch",
+    "RankedPrediction",
+    "ScreeningBatch",
+    "ScreeningResult",
+]

vendor/range_news/__init__.py

@@ -0,0 +1,64 @@
+"""Exact, CPU-first, traceable financial-news relevance screening."""
+
+from .api import (
+    RelevanceEngine,
+    available_backends,
+    predict,
+    predict_batch,
+    screen_arrow,
+    screen_batch,
+)
+from .customization import (
+    DefaultRanker,
+    DefaultTaxonomy,
+    GeneralEconomyTaxonomy,
+    Ranker,
+    Taxonomy,
+    TaxonomyBuilder,
+    copy_default_taxonomy,
+)
+from .models import (
+    ArrowScreeningBatch,
+    Article,
+    ArticleAdmissibilityStatus,
+    BackendInfo,
+    EvidencePath,
+    ExposureFamily,
+    ExposureRelevanceStatus,
+    Prediction,
+    PythonScreeningBatch,
+    RankedPrediction,
+    ScreeningBatch,
+    ScreeningResult,
+)
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "ArrowScreeningBatch",
+    "Article",
+    "ArticleAdmissibilityStatus",
+    "BackendInfo",
+    "DefaultRanker",
+    "DefaultTaxonomy",
+    "EvidencePath",
+    "ExposureFamily",
+    "ExposureRelevanceStatus",
+    "GeneralEconomyTaxonomy",
+    "Prediction",
+    "PythonScreeningBatch",
+    "RankedPrediction",
+    "Ranker",
+    "RelevanceEngine",
+    "ScreeningBatch",
+    "ScreeningResult",
+    "Taxonomy",
+    "TaxonomyBuilder",
+    "__version__",
+    "available_backends",
+    "copy_default_taxonomy",
+    "predict",
+    "predict_batch",
+    "screen_arrow",
+    "screen_batch",
+]

vendor/range_news/_core/__init__.py

@@ -0,0 +1 @@
+"""Private, deterministic financial-news relevance implementation."""