README.md

---

title: RANGE
emoji: 🔎
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: "6.27.0"
app_file: app.py
python_version: "3.10.13"
pinned: false
license: mit
suggested_hardware: zero-a10g
short_description: Your taxonomy. Your curated dataset. At speed.
tags:
- dataset-curation
- text-analysis
- information-extraction
- explainable-ai
- rust
---


# RANGE

**Rapid Annotation, Normalization, and Gating Engine**

**Python package coming soon. CPU today, optional CUDA for bulk screening.**

**Your taxonomy. Your curated dataset. At speed.**

Each successful run displays CPU processing time; batches also display records per
second for that run. Timing includes matching, decision evidence and engine setup
when needed, excluding input validation, queue/network wait and display rendering.
These small interactive runs are separate from the published bulk benchmarks.
The `curate` and `batch` demo endpoints append a readable timing output and include
numeric timing fields in their summaries; the single-record summary includes
`processing_timing`. The package API and matching algorithms are unchanged.

The custom-taxonomy tab automatically compares RANGE's actual Aho–Corasick matcher
with native Rust `str::find` searching each phrase. Both receive the same frozen
normalized text and phrases, apply identical token-boundary checks, and collect
all overlapping `(document, phrase, start, end)` matches. Their sorted outputs
must agree before times are shown. Setup, normalization, sorting, labels, and
Python/UI conversion are outside the timers; match-position collection is inside
both. The display uses the median of five warm runs, alternating execution order,
on one CPU thread. It makes no universal speedup or indexed-search claim.
Comparison input is bounded to 100 documents, 800 KB and 256 phrases, with a
100,000-match cap. If capped or mismatched, no timing comparison is shown.
The `curate` endpoint takes only taxonomy YAML and document JSON; comparison is
always enabled. The additional native method is a private hosted-demo diagnostic;
the published Windows CPU/CUDA preview downloads are unchanged.

RANGE applies your selection rules to text collections, assigns labels, and shows
matched evidence. Start with **Curate your text**, edit the example YAML, and pass
in documents from your own domain. **Build your taxonomy** includes an AI-agent
prompt and a review workflow. No timestamp or finance category is required.

The **Example taxonomy: General Economy** tab filters economic and financial news.
Its companion batch demo and taxonomy guide showcase temporal identities
and market relationships. Its benchmark is one workload, not a performance claim
for arbitrary taxonomies, biomedical corpora, billions of records, or NER models.
The generic engine uses normalized literal phrases and label-specific exclusions;
semantic enrichment such as GLiNER is future work.

Generic API: `/curate` takes taxonomy YAML and a JSON array of text strings.
It returns keep/drop decisions, user-defined labels, a fingerprint and capped
matched evidence. Local Python users can import `CurationEngine` and
`CurationTaxonomy` from `range_curate`. The distribution is
`range-curate`; the specialized economy API is in `range_curate.examples.general_economy`.

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 General Economy example 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.

## General Economy benchmark scope

| Implementation | Articles / second | Measurement |
| --- | ---: | --- |
| CUDA research record | **1,833,059** | Qualified warm screening of 10 million articles |
| CPU block-processing engine | **548,532–582,107** | Two qualified 10-million-article runs; 24–26% faster than matched CPU controls |
| Newer retained CUDA installation | **958,155** | Separate local installed-package qualification |

Measured on an Intel i7-10750H Windows laptop with 10 CPU workers; CUDA used an
RTX 2070 Max-Q. These are separate experiments, not a same-run CPU/GPU speedup.
The CUDA peak belongs to an earlier qualified implementation; later sessions
varied substantially. Do not combine its peak with later percentage gains.

Screening timings exclude file loading, imports, initialization and verification.
CUDA timings include transfers, exact CPU fallback and result assembly.
The live demo uses a different CPU environment and rich explanations, so these
figures are not its throughput or a service guarantee.

[Read the benchmark record](https://huggingface.co/spaces/Brianferrell787/range/blob/main/BENCHMARKS.md)

## Python package coming soon

We are preparing RANGE for straightforward Python installation, with CPU support
and an optional CUDA backend. Public package release, clean installation across
supported platforms and broader GPU compatibility are still ahead.
The current Space lets you explore the engine today.

## What we want to try next

- **Finish the release:** clean installs, supported platforms, documentation and
  validation of the exact wheels people will use.
- **Share work across taxonomies:** build on successful two-taxonomy experiments,
  then extend packaging and memory scheduling for more rule sets.
- **Choose CPU or CUDA by workload:** measure small batches, large batches and
  routing overhead before introducing automatic selection.
- **Target remaining matching ideas:** direct StringZilla integration and other
  CUSMART methods remain candidates, not demonstrated improvements.
- **Train optimizations on separate data:** investigate corpus-trained automata
  on larger future taxonomies. A fresh compiler-profile experiment was tested and did not qualify for adoption.

Recent alternatives did not beat the retained matcher. We keep negative results
and require exact outputs before considering a speed improvement.

## 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.0a3**, a deterministic CPU/Rust research alpha.
The Python distribution is `range-curate` and the import namespace is `range_curate`.
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.

## Generic demo limits

`/curate` accepts at most32 labels and256 phrases, each at most160 characters;
taxonomy YAML is limited to12,000 characters/48,000 bytes and has no anchors or
aliases. Documents are limited to100 rows,20,000 characters/80,000 UTF-8 bytes
per row and200,000 characters/800,000 UTF-8 bytes in total. JSON framing is also
bounded. Evidence is capped at50 spans per document; all matches still contribute
to decisions. No uploaded YAML is executed or used to access files.

## Retained CUDA implementation

The source and [preview installation files](https://huggingface.co/spaces/Brianferrell787/range/blob/main/cuda/README.md)
include the Phase60/61 CUDA implementation behind the peak benchmark. The hosted
interface remains CPU-based. CUDA preview support is Windows CPython3.10/sm75;
its kernels and private CPU fallback are byte-identical to Phase61. Public PyPI
release and broader GPU support are still pending. No benchmark rerun was made.